# Table of Contents - [Neon for Database-per-user - Neon Docs](#neon-for-database-per-user-neon-docs) - [Neon Serverless Postgres — Ship faster](#neon-serverless-postgres-ship-faster) - [Treat AI Like a Senior Dev, Not a Junior One - Neon](#treat-ai-like-a-senior-dev-not-a-junior-one-neon) - [Neon Docs - Neon Docs](#neon-docs-neon-docs) - [Neon AI Chat](#neon-ai-chat) - [Connect to Neon - Neon Docs](#connect-to-neon-neon-docs) - [Why Neon? - Neon Docs](#why-neon-neon-docs) - [Neon data migration guides - Neon Docs](#neon-data-migration-guides-neon-docs) - [Neon architecture - Neon Docs](#neon-architecture-neon-docs) - [Playing with Neon - Neon Docs](#playing-with-neon-neon-docs) - [Neon feature guides - Neon Docs](#neon-feature-guides-neon-docs) - [Neon use cases - Neon Docs](#neon-use-cases-neon-docs) - [Neon for AI Agents - Neon Docs](#neon-for-ai-agents-neon-docs) - [Database Branching Workflows - Neon](#database-branching-workflows-neon) - [Import Data Assistant - Neon Docs](#import-data-assistant-neon-docs) - [Neon for Development and Testing - Neon Docs](#neon-for-development-and-testing-neon-docs) - [Neon for SaaS apps - Neon Docs](#neon-for-saas-apps-neon-docs) --- # Neon for Database-per-user - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /[Use cases](/docs/use-cases/use-cases-overview) /Database-per-user Neon for Database-per-user ========================== How to configure Neon for multi-tenancy - plus a few design tips With its serverless and API-first nature, Neon is an excellent choice for building database-per-user applications (or apps where each user/customer has their own Postgres database). Neon is particularly well-suited for architectures that prioritize maximum database isolation, achieving the equivalent of instance-level isolation. This guide will help you get started with implementing this architecture. [](#multi-tenant-architectures-in-postgres) Multi-tenant architectures in Postgres ---------------------------------------------------------------------------------- In a multi-tenant architecture, a single system supports multiple users (tenants), each with access to manage their own data. In a database like Postgres, this setup requires careful structuring to keep each tenant’s data private, secure, and isolated—all while remaining efficient to manage and scale. Following these principles, there are three primary routes you could follow to implement multi-tenant architectures in Postgres: * Creating one separate database per user (the focus of this guide); * Creating one schema-per-user, within the same database; * And keeping your tenants separate within a shared schema. To better situate our use case, let’s briefly outline the differences between these architectures: ### [](#database-per-user) Database-per-user ![Database-per-user](/_next/image?url=%2Fdocs%2Fuse-cases%2Fdatabase_per_user.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) In a database-per-user design, each user’s data is fully isolated in its own database, eliminating any risk of data overlap. This setup is straightforward to design and highly secure. However, implementing this in managed Postgres databases has traditionally been challenging. For users of AWS RDS, Amazon Aurora, or similar services, two primary options have existed for achieving a database-per-user design: 1. **Using one large instance to host multiple user databases.** This option can be tempting due to the reduced number of instances to manage and (probably) lower infrastructure costs. But the trade-off is a higher demand for DBA expertise—this is a design that requires careful planning, especially at scale. Hosting all users on shared resources can impact performance, particularly if users have varying workload patterns, and if the instance fails, all customers are affected. Migrations and upgrades also become complex. 2. **Handling multiple instances, each hosting a single production database.** In this scenario, each instance scales independently, preventing resource competition between users and minimizing the risk of widespread failures. This is a much simpler design from the perspective of the database layer, but managing hundreds of instances in AWS can get very costly and complex. As the number of instances grows into the thousands, management becomes nearly impossible. As we’ll see later throughout this guide, Neon offers a third alternative by providing a logical equivalent to the instance-per-customer model with near-infinite scalability, without the heavy DevOps overhead. This solution involves creating one Neon project per customer. ### [](#schema-per-user) Schema-per-user ![Schema-per-user](/_next/image?url=%2Fdocs%2Fuse-cases%2Fschema_per_user.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) But before focusing on database-per-user, let’s briefly cover another multi-tenancy approach in Postgres: the schema-per-user model. Instead of isolating data by database, this design places all users in a single database, with a unique schema for each. In Neon, we generally don’t recommend this approach for SaaS applications, unless this is a design you’re already experienced with. This approach doesn’t reduce operational complexity or costs if compared to the many-databases approach, but it does introduce additional risks; it also limits the potential of Neon features like instant Point-in-Time Recovery (PITR), which in a project-per-customer model allows you to restore customer databases independently without impacting the entire fleet’s operations. More about this later. ### [](#shared-schema) Shared schema ![Shared schema](/_next/image?url=%2Fdocs%2Fuse-cases%2Fshared_schema.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Lastly, Postgres’s robustness actually makes it possible to ensure tenant isolation within a shared schema. In this model, all users' data resides within the same tables, with isolation enforced through foreign keys and row-level security. While this is a common choice—and can be a good starting point if you’re just beginning to build your app—we still recommend the project-per-user route if possible. Over time, as your app scales, meeting requirements within a shared schema setup becomes increasingly challenging. Enforcing compliance and managing access restrictions at the schema level grows more complex as you add more users. You’ll also need to manage very large Postgres tables, as all customer data is stored in the same tables. As these tables grow, additional Postgres fine-tuning will be required to maintain performance. [](#setting-up-neon-for-database-per-user) Setting up Neon for Database-per-user -------------------------------------------------------------------------------- Now that we’ve reviewed your options, let’s focus on the design choice we recommend for multi-tenancy in Neon: creating isolated databases for each user, with each database hosted on its own project. ### [](#database-per-user-project-per-user) Database-per-user = Project-per-user ![Project per user](/_next/image?url=%2Fdocs%2Fuse-cases%2Fproject_per_user.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) We recommend setting up one project per user, rather than, for example, using a branch per customer. A Neon [project](/docs/manage/overview) serves as the logical equivalent of an "instance" but without the management overhead. Here’s why we suggest this design: * **Straightforward scalability** Instead of learning how to handle large Postgres databases, this model allows you to simply create a new project when a user joins—something that can be handled automatically via the Neon API. This approach is very cost-effective, as we’ll see below. Databases remain small, keeping management at the database level simple. * **Better performance with lower costs** This design is also highly efficient in terms of compute usage. Each project has its own dedicated compute, which scales up and down independently per customer; a spike in usage for one tenant doesn’t affect others, and inactive projects remain practically free. * **Complete data isolation** By creating a dedicated project for each customer, their data remains completely separate from others, ensuring the highest level of security and privacy. * **Easier regional compliance** Each Neon project can be deployed in a specific region, making it easy to host customer data closer to their location. * **Per-customer PITR** Setting up a project per customer allows you to run [PITR on individual customers](/docs/guides/branch-restore) instantly, without risking disruption to your entire fleet. [](#managing-many-projects) Managing many projects -------------------------------------------------- As you scale, following a project-per-user design means eventually managing thousands of Neon projects. This might sound overwhelming, but it’s much simpler in practice than it seems—some Neon users [manage hundreds of thousands of projects](https://neon.tech/blog/how-retool-uses-retool-and-the-neon-api-to-manage-300k-postgres-databases) with just one engineer. Here’s why that’s possible: * **You can manage everything with the Neon API** The API allows you to automate every step of project management, including setting resource limits per customer and configuring resources. * **No infrastructure provisioning** New Neon projects are ready in milliseconds. You can set things up to create new projects instantly when new customers join, without the need to manually pre-provision instances. * **You only pay for active projects** Empty projects are virtually free thanks to Neon’s [scale-to-zero](/docs/guides/auto-suspend-guide) feature. If, on a given day, you have a few hundred projects that were only active for a few minutes, that’s fine—your bill won’t suffer. * **Subscription plans** To support this usage pattern, our pricing plans include a generous number of projects within the monthly subscription fee, allowing you to scale without a big budget: * The Launch plan includes 100 projects for $19/month. * The Scale plan includes 1,000 projects for $69/month. * The Business plan includes 5,000 projects for $700/month. ### [](#devtest-environments) Dev/test environments In Neon, [database branching](/docs/introduction/branching) is a powerful feature that enables you to create fast, isolated copies of your data for development and testing. You can use child branches as ephemeral environments that mirror your main testing database but operate independently, without adding to storage costs. This feature is a game-changer for dev/test workflows, as it reduces the complexity of managing multiple test databases while lowering non-prod costs significantly. To handle [dev/test](https://neon.tech/use-cases/dev-test) in a project-per-user design, consider creating a dedicated Neon project as your non-prod environment. This Neon project can serve as a substitute for the numerous non-prod instances you might maintain in RDS/Aurora. The methodology: * **Within the non-prod project, load your testing data into the production branch.** This production branch will serve as the primary source for all dev/test environments. * **Create ephemeral environments via child branches.** For each ephemeral environment, create a child branch from the production branch. These branches are fully isolated in terms of resources and come with an up-to-date copy of your testing dataset. * **Automate the process.** Use CI/CD and automations to streamline your workflow. You can reset child branches with one click to keep them in sync with the production branch as needed, maintaining data consistency across your dev/test environments. [](#designing-a-control-plane) Designing a Control Plane -------------------------------------------------------- Once you have everything set up, as your number of projects grows, you might want to create a control plane to stay on top of everything in a centralized manner. ### [](#the-catalog-database) The catalog database ![catalog database](/_next/image?url=%2Fdocs%2Fuse-cases%2Fcatalog_database.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) The catalog database is a centralized repository that tracks and manages all Neon projects and databases. It holds records for every Neon project your system creates. You can also use it to keep track of tenant-specific configurations, such as database names, regions, schema versions, and so on. You can set up your catalog database as a separate Neon project. When it's time to design its schema, consider these tips: * Use foreign keys to link tables like `project` and `payment` to `customer`. * Choose data types carefully: `citext` for case-insensitive text, `uuid` for unique identifiers to obscure sequence data, and `timestamptz` for tracking real-world time. * Track key operational data, like `schema_version`, in the `project` table. * Index wisely! While the catalog will likely remain smaller than user databases, it will grow—especially with recurring events like payments—so indexing is crucial for control plane performance at scale. * Start with essential data fields and plan for future extensions as needs evolve. * Standard Neon metadata (e.g., compute size, branch info) is accessible via the console. Avoid duplicating it in the catalog database unless separate access adds significant complexity. ### [](#automations) Automations To effectively scale a multi-tenant architecture, leveraging automation tools is essential. The Neon API will allow you to automate various tasks, such as creating and managing projects, setting usage limits, and configuring resources. Beyond the API, Neon offers several integrations to streamline your workflows: * **GitHub Actions** Neon's [GitHub integration](/docs/guides/neon-github-integration) allows you to automate database branching workflows directly from your repositories. By connecting a Neon project to a GitHub repository, you can set up actions that create or delete database branches in response to pull request events, facilitating isolated testing environments for each feature or bug fix. * **Vercel Integration** You can [connect your Vercel projects to Neon](/docs/guides/neon-github-integration) , creating database branches for each preview deployment. * **CI/CD pipelines** By combining Neon branching into your CI/CD, you can simplify your dev/test workflows by creating and deleting ephemeral environments automatically as child branches. * **Automated backups to your own S3** If you must keep your own data copy, you can [schedule regular backups](https://neon.tech/blog/nightly-backups-for-multiple-neon-projects) using tools like `pg_dump` in conjunction with GitHub Actions. [](#the-application-layer) The Application Layer ------------------------------------------------ Although the application layer isn’t our main focus, a common question developers ask us when approaching a multi-tenant architecture is: _Do I deploy one application environment per database, or connect all databases to a single application environment?_ Both approaches are viable, each with its own pros and cons. ### [](#shared-application-environments) Shared application environments ![shared application environments](/_next/image?url=%2Fdocs%2Fuse-cases%2Fshared_application_environments.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) #### [](#pros-of-shared-environments) Pros of shared environments * Managing a single application instance minimizes operational complexity. * Updates and new features are easy to implement since changes apply universally. * Operating one environment reduces infrastructure and maintenance costs. #### [](#cons-of-shared-environments) Cons of shared environments * A single application environment makes it difficult to offer tailored experiences for individual customers. * Compliance becomes challenging when users' databases span multiple regions. * Updates apply to all users simultaneously, which can be problematic for those needing specific software versions. * A single environment heightens the risk of data breaches, as vulnerabilities can impact all users. #### [](#advice) Advice * **Implement robust authorization** Ensure secure access as all users share the same application environment. * **Define user authentication and data routing** * Users provide their organization details during login. * Users access the application via an organization-specific subdomain. * The system identifies the user's organization based on their credentials. * **Monitor usage and performance** Regularly track application usage to prevent performance bottlenecks. * **Plan maintenance windows carefully** Minimize disruptions for all users by scheduling maintenance during low-usage periods. ### [](#isolated-application-environments) Isolated application environments ![isolated application environments](/_next/image?url=%2Fdocs%2Fuse-cases%2Fisolated_application_environments.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) In this architecture, each customer has instead a dedicated application environment alongside their own database. Similar to the shared environment option, this design has pros and cons: #### [](#pros-of-isolated-environments) Pros of isolated environments * Since each customer can now have a unique application environment, it’s easier to implement personalized features and configurations, to keep separate versions for particular customers, and so on. * Compliance is also simpler if you’re handling multiple regions. Deploying the application in multiple regions can also help with latency. * This design also opens the door for customers to control their own upgrade schedules, e.g., via defining their own maintenance windows. #### [](#cons-of-isolated-environments) Cons of isolated environments * This design has an obvious tradeoff: it comes with higher complexity of deployment, monitoring, and maintenance. * You’ll need to think about how to route optimal resource utilization across multiple environments, and how to keep observability on-point to diagnose issues. * Operating separate environments for each customer might also lead to higher costs. #### [](#advice) Advice If you decide to implement isolated environments, here’s some advice to consider: * Design your architecture to accommodate growth, even if your setup is small today. * Similarly as you’re doing with Neon projects, take advantage of automation tools to streamline the creation and management of your application environments. * Set up proper monitoring to track key metrics across all environments. [](#migrating-schemas) Migrating Schemas ---------------------------------------- In a database-per-user design, it is common to have the same schema for all users/databases. Any changes to the user schema will most likely be rolled out to all individual databases simultaneously. In this section, we teach you how to use DrizzleORM, GitHub Actions, the Neon API, and a couple of custom template scripts to manage many databases using the same database schema. ### [](#example-app) Example app To walk you through it, we’ve created example code [in this repository](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle) . The example includes 4 Neon databases, all using Postgres 16 and all deployed to AWS us-east-1. The schema consists of three tables, `users`, `projects` and `tasks`. You can see the schema here: [schema.ts](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle/blob/main/src/db/schema.ts) , and for good measure, here’s the raw SQL equivalent: [schema.sql](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle/blob/main/schema.sql) . This default schema is referenced by each of the `drizzle.config.ts` files that have been created for each customer. ### [](#workflow-using-drizzle-orm-and-github-actions) Workflow using Drizzle ORM and GitHub Actions #### [](#creating-neon-projects-via-a-cli-script) Creating Neon projects via a CLI script Our example creates new Neon projects via the command line, using the following script: // src/scripts/create.js import { Command } from 'commander'; import { createApiClient } from '@neondatabase/api-client'; import 'dotenv/config'; const program = new Command(); const neonApi = createApiClient({ apiKey: process.env.NEON_API_KEY, }); program.option('-n, --name ', 'Name of the company').parse(process.argv); const options = program.opts(); if (options.name) { console.log(`Company Name: ${options.name}`); (async () => { try { const response = await neonApi.createProject({ project: { name: options.name, pg_version: 16, region_id: 'aws-us-east-1', }, }); const { data } = response; console.log(data); } catch (error) { console.error('Error creating project:', error); } })(); } else { console.log('No company name provided'); } This script utilizes the `commander` library to create a simple command-line interface (CLI) and the Neon API's `createProject` method to set up a new project. Ensure that your Neon API key is stored in an environment variable named `NEON_API_KEY`. To execute the script and create a new Neon project named "ACME Corp" with PostgreSQL version 16 in the aws-us-east-1 region, run: npm run create -- --name="ACME Corp" In this example, the same approach was used to create the following projects: * ACME Corp * Payroll Inc * Finance Co * Talent Biz To interact with the Neon API, you'll need to generate an API key. For more information, refer to the Neon documentation on [creating an API key](https://api-docs.neon.tech/reference/createapikey) . #### [](#generating-a-workflow-to-prepare-for-migrations) Generating a workflow to prepare for migrations // src/scripts/generate.js import { existsSync, mkdirSync, writeFileSync } from 'fs'; import { execSync } from 'child_process'; import { createApiClient } from '@neondatabase/api-client'; import { Octokit } from 'octokit'; import 'dotenv/config'; import { encryptSecret } from '../utils/encrypt-secret.js'; import { drizzleConfig } from '../templates/drizzle-config.js'; import { githubWorkflow } from '../templates/github-workflow.js'; const octokit = new Octokit({ auth: process.env.PERSONAL_ACCESS_TOKEN }); const neonApi = createApiClient({ apiKey: process.env.NEON_API_KEY }); const repoOwner = 'neondatabase-labs'; const repoName = 'neon-database-per-tenant-drizzle'; let secrets = []; (async () => { // Ensure configs directory exists if (!existsSync('configs')) mkdirSync('configs'); // Fetch GitHub public key for encrypting secrets const { data: publicKeyData } = await octokit.request( `GET /repos/${repoOwner}/${repoName}/actions/secrets/public-key`, { headers: { 'X-GitHub-Api-Version': '2022-11-28' } } ); // List all Neon projects const { data: { projects }, } = await neonApi.listProjects(); await Promise.all( projects.map(async (project) => { const { id, name } = project; // Fetch database connection URI const { data: { uri }, } = await neonApi.getConnectionUri({ projectId: id, database_name: 'neondb', role_name: 'neondb_owner', }); // Prepare variables const safeName = name.replace(/\s+/g, '-').toLowerCase(); const path = `configs/${safeName}`; const file = 'drizzle.config.ts'; const envVarName = `${safeName.replace(/-/g, '_').toUpperCase()}_DATABASE_URL`; const encryptedValue = await encryptSecret(publicKeyData.key, uri); // Store environment variable name for later use secrets.push(envVarName); // Create project directory and config file if not present if (!existsSync(path)) mkdirSync(path); if (!existsSync(`${path}/${file}`)) { writeFileSync(`${path}/${file}`, drizzleConfig(safeName, envVarName)); console.log(`Created drizzle.config for: ${safeName}`); } // Add encrypted secret to GitHub await octokit.request(`PUT /repos/${repoOwner}/${repoName}/actions/secrets/${envVarName}`, { owner: repoOwner, repo: repoName, secret_name: envVarName, encrypted_value: encryptedValue, key_id: publicKeyData.key_id, headers: { 'X-GitHub-Api-Version': '2022-11-28' }, }); // Generate migrations using drizzle-kit execSync(`drizzle-kit generate --config=${path}/${file}`, { encoding: 'utf-8' }); console.log(`Ran drizzle-kit generate for: ${safeName}`); }) ); // Ensure GitHub Actions workflow directories exist if (!existsSync('.github')) mkdirSync('.github'); if (!existsSync('.github/workflows')) mkdirSync('.github/workflows'); // Generate GitHub workflow file const workflow = githubWorkflow(secrets); writeFileSync(`.github/workflows/run-migrations.yml`, workflow); console.log('GitHub Actions workflow created.'); })(); The script above goes through these steps: 1. Ensures the `configs` directory exists, creating it if necessary. 2. Retrieves the GitHub public key for encrypting secrets. 3. Lists all projects in your Neon account. 4. For each project: * Retrieves the connection URI from Neon. * Sanitizes project names for safe usage in directory names and environment variables. * Creates DrizzleORM config files. * Encrypts secrets and adds them to the GitHub repository. * Generates migrations using `drizzle-kit`. 5. Finally, it generates GitHub Actions workflow that includes all generated environment variables for running migrations. 6. To run the script, use the following command: npm run generate Ensure the following environment variables are set: * `NEON_API_KEY`: Your Neon API key. * `PERSONAL_ACCESS_TOKEN`: Your GitHub personal access token. And update `repoOwner` and `repoName` to match your repository details. Here’s an example output for the Drizzle configuration: // src/configs/acme-corp/drizzle.config.ts import 'dotenv/config'; import { defineConfig } from 'drizzle-kit'; export default defineConfig({ out: './drizzle/acme-corp', schema: './src/db/schema.ts', dialect: 'postgresql', dbCredentials: { url: process.env.ACME_CORP_DATABASE_URL!, }, }); And for the GitHub workflow: // .github/workflows/run-migrations.yml name: Migrate changes on: pull_request: types: [closed] branches: - main workflow_dispatch: env: TALENT_BIZ_DATABASE_URL: ${{ secrets.TALENT_BIZ_DATABASE_URL }} PAYROLL_INC_DATABASE_URL: ${{ secrets.PAYROLL_INC_DATABASE_URL }} ACME_CORP_DATABASE_URL: ${{ secrets.ACME_CORP_DATABASE_URL }} FINANCE_CO_DATABASE_URL: ${{ secrets.FINANCE_CO_DATABASE_URL }} jobs: migrate: runs-on: ubuntu-latest if: github.event.pull_request.merged == true steps: - name: Checkout repository uses: actions/checkout@v4 - name: Set up Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm ci - name: Run migration script run: node src/scripts/migrate.js #### [](#running-migrations) Running migrations Now, we’re ready to run migrations: // src/scripts/migrate.js import { readdirSync, existsSync } from 'fs'; import path from 'path'; import { execSync } from 'child_process'; import { fileURLToPath } from 'url'; (async () => { const configDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../configs'); if (existsSync(configDir)) { const customers = readdirSync(configDir); const configPaths = customers .map((customer) => path.join(configDir, customer, 'drizzle.config.ts')) .filter((filePath) => existsSync(filePath)); console.log('Found drizzle.config.ts files:', configPaths); configPaths.forEach((configPath) => { console.log(`Running drizzle-kit for: ${configPath}`); execSync(`npx drizzle-kit migrate --config=${configPath}`, { encoding: 'utf-8' }); }); } else { console.log('The configs directory does not exist.'); } })(); This script: * Only runs after a pull request (PR) has been merged. It reads through the configs directory and applies the migrations defined in each `drizzle.config.ts` file for every project or customer, ensuring that all databases are using the same schema. * Uses `npx` to run the `drizzle-kit migrate` command against each `drizzle.config.ts` file, ensuring that the schema is applied to all databases. The source code for this migration script is located at: `src/scripts/migrate.js`. This approach automatically includes any new projects or customers added to the system, as well as schema changes that need to be applied across all databases. ### [](#summary) Summary Here’s an overview of the workflow: * We used a script to automate the creation of DrizzleORM configuration files (`drizzle.config.ts`) and securely store database connection strings as GitHub secrets. * We used a migration script to iterate through the configs directory and apply schema changes to all databases via `drizzle-kit migrate`. * The GitHub Actions workflow triggers migrations automatically when a PR is merged. Environment variables for each project are explicitly injected into the workflow, giving DrizzleORM access to the connection strings needed for schema updates. [](#backing-up-projects-to-your-own-s3) Backing up Projects to Your Own S3 -------------------------------------------------------------------------- As a managed database, Neon already takes care of securing your data, always keeping a full copy of your dataset in object storage. But if your use case or company demands that you also keep a copy of your data in your own S3, this section covers how to automate the process via a scheduled GitHub Action. A more extensive explanation can be found in this two-part blog post series: [Part 1](https://neon.tech/blog/how-to-create-an-aws-s3-bucket-for-postgres-backups) , [Part 2](https://neon.tech/blog/nightly-backups-for-multiple-neon-projects) . ### [](#aws-iam-configuration) AWS IAM configuration First, GitHub must be added as an identity provider to allow the Action to use your AWS credentials. To create a new Identity Provider, navigate to IAM > Access Management > Identity Providers, and click Add provider. ![S3 backup IAM configuration](/_next/image?url=%2Fdocs%2Fuse-cases%2Fs3_backup_iam_config.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) On the next screen select OpenID Connect and add the following to the Provider URL and Audience fields. 1. Provider URL: [https://token.actions.githubusercontent.com](https://token.actions.githubusercontent.com) 2. Audience: `sts.amazonaws.com` When you’re done, click **Add Provider**. You should now see this provider is visible in the list under **IAM > Access Management > Identity Providers**. Now, you must create a role, which is an identity that you can assume to obtain temporary security credentials for specific tasks or actions within AWS. Navigate to **IAM > Access Management > Roles**, and click **Create role**. On the next screen you can create a Trusted Identity for the Role. Select **Trusted Identity**. On the next screen, select **Web Identity**, then select `token.actions.githubusercontent.com` from the **Identity Provider** dropdown menu. ![S3 backup select trusted entity](/_next/image?url=%2Fdocs%2Fuse-cases%2Fs3_select_trusted_entity.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Once you select the Identity Provider, you’ll be shown a number of fields to fill out. Select `sts.amazonaws.com` from the **Audience** dropdown menu, then fill out the GitHub repository details as per your requirements. When you’re ready, click **Next**. For reference, the options shown in the image below are for this repository. ![S3 backup web identity](/_next/image?url=%2Fdocs%2Fuse-cases%2Fs3_web_identity.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) You can skip selecting anything from the Add Permissions screen and click **Next** to continue. On this screen give the **Role** a name and description. You’ll use the Role name in the code for the GitHub Action. When you’re ready click **Create role**. ### [](#s3-bucket-policy) S3 bucket policy This section assumes you already have an S3 bucket. If you need instructions on how to create a bucket, refer to [this blog post](https://neon.tech/blog/how-to-create-an-aws-s3-bucket-for-postgres-backups) . To ensure the Role being used in the GitHub Action can perform actions on the S3 bucket, you’ll need to update the bucket policy. Select your bucket then select the Permissions tab and click **Edit**. ![S3 backup web identity](/_next/image?url=%2Fdocs%2Fuse-cases%2Fs3_bucket_policy.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) You can now add the following policy which grants the Role you created earlier access to perform S3 List, Get, Put and Delete actions. Replace the Role name (`neon-multiple-db-s3-backups-github-action`) with your Role name and replace the S3 bucket name (`neon-multiple-db-s3-backups`) with your S3 bucket name. { 'Version': '2012-10-17', 'Statement': [\ {\ 'Effect': 'Allow',\ 'Principal':\ { 'AWS': 'arn:aws:iam::627917386332:role/neon-multiple-db-s3-backups-github-action' },\ 'Action': ['s3:ListBucket', 's3:GetObject', 's3:PutObject', 's3:DeleteObject'],\ 'Resource':\ [\ 'arn:aws:s3:::neon-multiple-db-s3-backups',\ 'arn:aws:s3:::neon-multiple-db-s3-backups/*',\ ],\ },\ ], } When you’re ready click **Save** changes. ### [](#github-secrets) GitHub secrets Create the following GitHub Secrets to hold various values that you likely won’t want to expose or repeat in code: * `AWS_ACCOUNT_ID`: This can be found by clicking on your user name in the AWS console. * `S3_BUCKET_NAME`: In my case, this would be, neon-multiple-db-s3-backups * `IAM_ROLE`: In my case this would be, neon-multiple-db-s3-backups-github-action ### [](#scheduled-pgdumprestore-github-action) Scheduled pg\_dump/restore GitHub Action Before diving into the code, here’s a look at this example in the Neon console dashboard. There are three databases set up for three fictional customers, all running Postgres 16 and all are deployed to us-east-1. We will be backing up each database into its own folder within an S3 bucket, with different schedules and retention periods. All the code in this example lives [in this repository](https://github.com/neondatabase-labs/neon-multiple-db-s3-backups) . ![S3 backup three databases](/_next/image?url=%2Fdocs%2Fuse-cases%2Fs3_backup_three_databases.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Using the same naming conventions, there are three new files in the \`\`.github/workflows\` folder in the repository: 1. `paycorp-payments-prod.yml` 2. `acme-analytics-prod.yml` 3. `paycorp-payments-prod.yml` All the Actions are technically the same, (besides the name of the file), but there are several areas where they differ. These are: 1. The workflow name 2. The `DATABASE_URL` 3. The `RETENTION` period For example, in the first `.yml` file, the workflow name is `acme-analytics-prod`, the `DATABASE_URL` points to `secrets.ACME_ANALYTICS_PROD`, and the `RETENTION` period is 7 days. Here’s the full Action, and below the code snippet, we'll explain how it all works. // .github/workflows/acme-analytics-prod.yml name: acme-analytics-prod on: schedule: - cron: '0 0 * * *' # Runs at midnight UTC workflow_dispatch: jobs: db-backup: runs-on: ubuntu-latest permissions: id-token: write env: RETENTION: 7 DATABASE_URL: ${{ secrets.ACME_ANALYTICS_PROD }} IAM_ROLE: ${{ secrets.IAM_ROLE }} AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }} S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }} AWS_REGION: 'us-east-1' PG_VERSION: '16' steps: - name: Install PostgreSQL run: | sudo apt install -y postgresql-common yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh sudo apt install -y postgresql-${{ env.PG_VERSION }} - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }} aws-region: ${{ env.AWS_REGION }} - name: Set file, folder and path variables run: | GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').gz" FOLDER_NAME="${{ github.workflow }}" UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}" echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV - name: Create folder if it doesn't exist run: | if ! aws s3api head-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/" 2>/dev/null; then aws s3api put-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/" fi - name: Run pg_dump run: | /usr/lib/postgresql/${{ env.PG_VERSION }}/bin/pg_dump ${{ env.DATABASE_URL }} | gzip > "${{ env.GZIP_NAME }}" - name: Empty bucket of old files run: | THRESHOLD_DATE=$(date -d "-${{ env.RETENTION }} days" +%Y-%m-%dT%H:%M:%SZ) aws s3api list-objects --bucket ${{ env.S3_BUCKET_NAME }} --prefix "${{ env.FOLDER_NAME }}/" --query "Contents[?LastModified<'${THRESHOLD_DATE}'] | [?ends_with(Key, '.gz')].{Key: Key}" --output text | while read -r file; do aws s3 rm "s3://${{ env.S3_BUCKET_NAME }}/${file}" done - name: Upload to bucket run: | aws s3 cp "${{ env.GZIP_NAME }}" "${{ env.UPLOAD_PATH }}" --region ${{ env.AWS_REGION }} Starting from the top, there are a few configuration options: #### [](#action-configuration) Action configuration name: acme-analytics-prod on: schedule: - cron: '0 0 * * *' # Runs at midnight UTC workflow_dispatch: * `name`: This is the workflow name and will also be used when creating the folder in the S3 bucket. * `cron`: This determines how often the Action will run, take a look a the GitHub docs where the [POSIX cron syntax](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) is explained. #### [](#environment-variables) Environment variables env: RETENTION: 7 DATABASE_URL: ${{ secrets.ACME_ANALYTICS_PROD }} IAM_ROLE: ${{ secrets.IAM_ROLE }} AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }} S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }} AWS_REGION: 'us-east-1' PG_VERSION: '16' * `RETENTION`: This determines how long a backup file should remain in the S3 bucket before it’s deleted. * `DATABASE_URL`: This is the Neon Postgres connection string for the database you’re backing up. * `IAM_ROLE`: This is the name of the AWS IAM Role. * `AWS_ACCOUNT_ID`: This is your AWS Account ID. * `S3_BUCKET_NAME`: This is the name of the S3 bucket where all backups are being stored. * `AWS_REGION`: This is the region where the S3 bucket is deployed. * `PG_VERSION`: This is the version of Postgres to install. #### [](#github-secrets) GitHub Secrets As we mentioned above, several of the above environment variables are defined using secrets. These variables can be added to **Settings > Secrets and variables > Actions**. Here’s a screenshot of the GitHub repository secrets including the connection string for the fictional ACME Analytics Prod database. ![S3 backup three databases](/_next/image?url=%2Fdocs%2Fuse-cases%2Fgithub_secrets.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) #### [](#action-steps) Action steps This step installs Postgres into the GitHub Action’s virtual environment. The version to install is defined by the `PG_VERSION` environment variable. **Install Postgres** - name: Install PostgreSQL run: | sudo apt install -y postgresql-common yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh sudo apt install -y postgresql-${{ env.PG_VERSION }} **Configure AWS credentials** This step configures AWS credentials within the GitHub Action virtual environment, allowing the workflow to interact with AWS services securely. - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }} aws-region: ${{ env.AWS_REGION }} **Set file, folder and path variables** In this step I’ve created three variables that are all output to `GITHUB_ENV`. This allows me to access the values from other steps in the Action. - name: Set file, folder and path variables run: | GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').gz" FOLDER_NAME="${{ github.workflow }}" UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}" echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV The three variables are as follows: 1. `GZIP_NAME`: The name of the `.gz` file derived from the date which would produce a file name similar to, `October-21-2024@07:53:02.gz` 2. `FOLDER_NAME`: The folder where the `.gz` files are to be uploaded 3. `UPLOAD_PATH`: This is the full path that includes the S3 bucket name, folder name and `.gz` file **Create folder if it doesn’t exist** This step creates a new folder (if one doesn’t already exist) inside the S3 bucket using the `FOLDER_NAME` as defined in the previous step. [](#final-remarks) Final remarks -------------------------------- You can create as many of these Actions as you need. Just be careful to double check the `DATABASE_URL` to avoid backing up a database to the wrong folder. #### important GitHub Actions will timeout after ~6 hours. The size of your database and how you’ve configured it will determine how long the `pg_dump` step takes. If you do experience timeout issues, you can self host [GitHub Action runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) . [PreviousVariable traffic](/docs/use-cases/variable-traffic) [NextAI Agents](/docs/use-cases/ai-agents) Last updated on April 17, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Multi-tenant architectures in Postgres](#multi-tenant-architectures-in-postgres) * [Setting up Neon for Database-per-user](#setting-up-neon-for-database-per-user) * [Managing many projects](#managing-many-projects) * [Designing a Control Plane](#designing-a-control-plane) * [The Application Layer](#the-application-layer) * [Migrating Schemas](#migrating-schemas) * [Backing up Projects to Your Own S3](#backing-up-projects-to-your-own-s3) * [Final remarks](#final-remarks) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/use-cases/database-per-user.md) --- # Neon Serverless Postgres — Ship faster [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Ship faster with Postgres ========================= The database developers trust, on a serverless platform designed to help you build reliable and scalable applications faster. [Start for Free](https://console.neon.tech/signup) [Talk to Us](/contact-sales) ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0ibm9uZSI+PHBhdGggc3Ryb2tlPSIjZmZmIiBzdHJva2UtbGluZWNhcD0ic3F1YXJlIiBzdHJva2Utd2lkdGg9IjIiIGQ9Ik0xNCAyNy4zMzFINC42Njd2LTkuMzMzTTI3LjMzMyAxMy45OThWNC42NjVIMThNNS4yMzggMjYuNzYgMjYuNzYyIDUuMjM2Ii8+PC9zdmc+) Scaling ------- ### Scaling Focus on building applications with time and money-saving features like instant provisioning, autoscaling according to load, and scale to zero. [Discover Autoscaling](/docs/introduction/autoscaling) ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0ibm9uZSI+PHBhdGggc3Ryb2tlPSIjZmZmIiBzdHJva2UtbGluZWNhcD0ic3F1YXJlIiBzdHJva2Utd2lkdGg9IjIiIGQ9Ik0yLjUgMjIuNWgyMk0xOS41IDEwLjVoLTVhNSA1IDAgMCAwLTUgNXY3Ii8+PGNpcmNsZSBjeD0iMjgiIGN5PSIyMi41IiByPSIzIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iMiIvPjxjaXJjbGUgY3g9IjIzIiBjeT0iMTAuNSIgcj0iMyIgc3Ryb2tlPSIjZmZmIiBzdHJva2Utd2lkdGg9IjIiLz48L3N2Zz4=) Branching --------- ### Branching Instantly branch your data and schema to access isolated DB copies for development, CI/CD, and schema migrations with copy-on-write storage. [Explore Branching](/docs/introduction/branching) ![](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fbg.3d093f83.jpg&w=3840&q=100&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Trusted in production by thousands of teams. -------------------------------------------- * ![Vercel V0](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9IiNmZmYiIGFyaWEtaGlkZGVuPSJ0cnVlIiBjbGFzcz0ic2l6ZS0xMCIgdmlld0JveD0iLTUgMCA0NSAyMCI+PHBhdGggZD0iTTIzLjM5MiAwaDkuNTI3YTYuOTk1IDYuOTk1IDAgMCAxIDYuOTk1IDYuOTk1djkuMDg2SDM2VjYuOTk1cTAtLjE0LS4wMTEtLjI3N2wtOS41MjcgOS4zNjEuMDk2LjAwMmg5LjQ0MnYzLjY5NUgyNi41NmMtMy44NjQgMC03LjA4MS0zLjE2Mi03LjA4MS03LjAyNVYzLjY4OWgzLjkxM3Y5LjA2MnEwIC4yNjIuMDQuNTE2TDMzLjE2OCAzLjdhMyAzIDAgMCAwLS4yNS0uMDFoLTkuNTI2ek0xMy43NjkgMTkuMDk2IDAgMy42ODhoNS41NGw4LjA4MyA5LjA0NlYzLjY4OGg0LjEzdjEzLjg4N2MwIDIuMDk2LTIuNTg4IDMuMDgzLTMuOTg0IDEuNTIiLz48L3N2Zz4=) * ![Zimmer Biomet](/_next/static/svgs/7f02b9671daf78d29a1aff9900c27428.svg) * ![Retool](/_next/static/svgs/5e43faa91c0e64a308dad433f12b6cc7.svg) * ![Boston Consulting Group](/_next/static/svgs/0ec024e581a9ad1a8fd4067237130f92.svg) * ![Outfront Media](/_next/static/svgs/357153973509682f51a32c7f5829b2d8.svg) * ![Replit](/_next/static/svgs/bc51018c075b240eb3bd1032ea0c8b3b.svg) Instant Provisioning -------------------- No waiting. No config. Provisioned in 300ms postgresql://example@ep-938132.eu-central-1.aws.neon.tech/primary Works with your stack ----------------------- Integrate it into your language or framework within minutes and unlock a simpler developer workflow. [See all examples](/docs/guides/guides-intro) ![](/_next/static/svgs/10dc59376dbc4407529140b059de0c37.svg)Next.js![](/_next/static/svgs/f586b4ee268939235809c4f8e9634251.svg)Drizzle![](/_next/static/svgs/6ade259658926475c0eb792e61111c98.svg)Prisma![](/_next/static/svgs/bee5282584f26a60944dfc6f92efb527.svg)Python![](/_next/static/svgs/f1fc4356fcf3e301a0b84466845bbe8f.svg)Ruby![](/_next/static/svgs/39d40e4342ea5abb651ec618fd159053.svg)Rust![](/_next/static/svgs/4914c82061c06def4904591775d95785.svg)Go import { neon } from '@neondatabase/serverless'; export async function GET() { const sql = neon(process.env.DATABASE_URL); const rows = await sql("SELECT * FROM posts"); return Response.json({ rows }) } Lightning fast. Edge ready. --------------------------- ![](data:image/svg+xml;charset=utf-8,%3Csvg width='828' height='684' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) ![](data:image/svg+xml;charset=utf-8,%3Csvg width='828' height='684' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) ![](data:image/svg+xml;charset=utf-8,%3Csvg width='351' height='298' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) The Neon serverless driver, designed for fast queries over HTTP `import { neon } from '@neondatabase/ serverless';const sql = neon('postgresql:// usr:pass@proj.us-east-2.aws.neon.tech/db');const posts = await sql('SELECT * FROM posts');`[Get the Serverless Driver](/docs/serverless/serverless-driver) ![](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fphone-camera.27658a1d.png&w=384&q=100&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Better database. For modern workflows. ---------------------------------------- ![](data:image/svg+xml;charset=utf-8,%3Csvg width='960' height='384' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) **Boost your performance with instant [read replicas](/docs/introduction/read-replicas) .** They scale down to zero when idle and don't use additional storage. **Easy database ops via the [API](https://api-docs.neon.tech/reference/getting-started-with-neon-api) and [CLI](/docs/reference/neon-cli) .** Manage thousands of databases programmatically. **Instant [Point-in-time recovery](/blog/point-in-time-recovery-in-postgres) .** Up to 30 days granularity down to the transaction or second. Unleashing Cutting- Edge AI Applications. ------------------------------------------- The HNSW index algorithm streamlines performance, making high-dimensional vector search remarkably efficient. [Power your AI apps with Postgres](/ai) ![](data:image/svg+xml;charset=utf-8,%3Csvg width='1160' height='1160' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) ReliableScalabilityHigh compatibilityBlazingly fast searchWorks with PGVECTORWorks with langchain; Thousands of databases. Zero overhead. ---------------------------------------- ![](data:image/svg+xml;charset=utf-8,%3Csvg width='1920' height='474' xmlns='http://www.w3.org/2000/svg' version='1.1'%3E%3C/svg%3E) Use the Neon API to deploy [database-per-tenant architectures](/blog/how-retool-uses-retool-and-the-neon-api-to-manage-300k-postgres-databases) . Scale to fleets of thousands of databases without touching a server. Rest easy knowing scale to zero keeps costs low. Industry leaders trust Neon ----------------------------- [Dive into success stories](/case-studies) ![Supergood.ai](/_next/static/svgs/03731b59b0dbf4dc3b09def19e5d25ec.svg) > Neon allows us to develop much faster than we’ve even been used to ![Alex Klarfeld](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Falex-klarfeld.b8bd71ba.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Alex Klarfeld – CEO and co-founder of Supergood.ai ![Koyeb](/_next/static/svgs/db1030bbd306eba437adb54691e31dea.svg) > Neon's serverless philosophy is aligned with our vision: no infrastructure to manage, no servers to provision, no database cluster to maintain ![Edouard Bonlieu](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fedouard-bonlieu.d69ae917.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Edouard Bonlieu – Co-founder at Koyeb ![Topo.io](/_next/static/svgs/f232265d4bedb9cce70f66a4838ee013.svg) > The killer feature that convinced us to use Neon was branching: it keeps our engineering velocity high ![Léonard Henriquez](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fleonard-henriquez.1ab5608f.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Léonard Henriquez – Co-founder and CTO, Topo.io ![Retool](/_next/static/svgs/5e43faa91c0e64a308dad433f12b6cc7.svg) > We've been able to automate virtually all database tasks via the Neon API, saving us a tremendous amount of time and engineering effort ![Himanshu Bhandoh](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fhimanshu-bhandoh.95baee7b.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Himanshu Bhandoh – Software Engineer at Retool Trusted Postgres ---------------- [![](/_next/static/media/github.e7e489f2.jpg)\ \ neondatabase/neon](https://github.com/neondatabase/neon) ![](/_next/static/media/digit.d4d71d86.jpg) **Databases under management.** Postgres for the World. ![](/_next/static/media/elephant.c07449d7.jpg) **100% Postgres.** Not a fork, not a rewrite. [![](/_next/static/media/soc.bf1f4421.jpg)![](/_next/static/media/soc-md.43810ef9.jpg)\ \ SOC2 Compliance](/blog/soc2-type2) Features of tomorrow. Available today. ---------------------------------------- [Get Started](https://console.neon.tech/signup) --- # Treat AI Like a Senior Dev, Not a Junior One - Neon [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) [AI](/blog/category/ai) Apr 24, 2025 Treat AI Like a Senior Dev, Not a Junior One ============================================ Better results start with a better mental model for working with LLMs Most developers approach AI coding with the wrong mental model. The tendency, exacerbated by the vibe coding trend, is to let AI take the wheel. “Build me a UI using Tailwind that lets users see their account info” is an example initial request, followed by more and more short (and curt) instructions. The result? Hallucinations, slop, and edge cases missed. But by taking a more strategic approach to working with AI coding, you can achieve far better results and move from [producing programming to producing products](https://dylanbeattie.net/2025/04/11/the-problem-with-vibe-coding.html) .  The first way to do this is through better tactical prompting. By [seeing prompting as a new developer discipline](https://neon.tech/blog/prompt-engineering-developer-discipline) , you can significantly improve your results from AI coding. Just like developers follow principles such as DRY and SOLID, prompting should be approached with the same rigor they bring to traditional code: designing, refining, and optimizing for clear outputs. **The second is to understand that LLMs shine when treated like a senior teammate: someone who can think with you, given the right context and room to reason.** This simple shift in mindset–framing AI as a senior developer rather than a junior one–enables better prompting, better outputs, and more robust systems. This approach transforms AI from a code generator into a programming partner capable of exploring architectural decisions, suggesting testing strategies, and identifying potential pitfalls before they become production issues. You’ll find yourself spending less time fixing AI-generated mistakes and more time leveraging its capabilities to solve genuinely challenging problems. So, what does it mean to treat AI like a senior developer? [](#give-your-ai-a-prd) Give Your AI A PRD ------------------------------------------ Good developers don’t start coding without understanding the problem. Senior engineers know that requirements gathering is the foundation of quality code. So why are we giving AI one-line prompts and expecting production-ready results? **Writing a clear, structured task description, like a PRD, fundamentally changes how AI responds to your requests.** When you include context, examples, constraints, and expected outcomes, you transform vague ideas into actionable specifications. This approach mirrors how experienced developers communicate with each other–through comprehensive requirements that leave little room for misinterpretation. ### [](#example) Example _TASK: Build a Currency Conversion API Service_ _PROJECT CONTEXT:_ * _Part of our global payment processing platform_ * _Will be used by both our web and mobile applications_ * _Expected traffic: ~5,000 conversions per hour_ * Must comply with financial regulations in EU, US, and APAC regions _USER STORIES:_ * _As a user making an international payment, I want to see the exact amount I’ll pay in my local currency before confirming._ * _As a finance team member, I need accurate conversion records for reconciliation and auditing._ * _As a product manager, I need conversion rates to update at least daily to ensure accuracy._ _TECHNICAL REQUIREMENTS:_ * _Backend function for REST API endpoint_ * _Use the official European Central Bank (ECB) API as the data source for rates_ * _Cache exchange rates (max 1 hour TTL) to reduce external API calls_ * _Implement proper error handling with descriptive messages_ * _Include comprehensive logging for debugging and audit trails_ _INPUTS:_ * _amount: Decimal number (required)_ * _from\_currency: ISO 4217 three-letter code (required)_ * _to\_currency: ISO 4217 three-letter code (required)_ * _reference\_date: ISO 8601 date format (optional, defaults to current date)_ _OUTPUTS:_ * _JSON response with:_ * _original\_amount: The input amount_ * _converted\_amount: The converted amount (rounded to 2 decimal places)_ * _exchange\_rate: The rate used for conversion_ * _from\_currency: Original currency code_ * _to\_currency: Target currency code_ * _timestamp: ISO 8601 timestamp of when conversion was performed_ * _reference\_date: The date for which the exchange rate was retrieved_ _ERROR HANDLING:_ * _Invalid currency codes: Return clear error identifying the invalid code_ * _ECB API unavailable: Fallback to cached rates if available, otherwise return service unavailable_ * _Invalid amount format: Return validation error with example of correct format_ _DEPLOYMENT ENVIRONMENT:_ * _AWS Lambda with Node.js 18 runtime_ * _Redis for caching layer_ This level of detail gives the AI a comprehensive understanding of what you’re building, why you’re building it, and how it should behave. You can even use a service such as [ChatPRD](https://www.chatprd.ai/) to create the initial design doc.  [](#allow-the-ai-to-ask-questions) Allow the AI to Ask Questions ---------------------------------------------------------------- If something’s unclear, a senior developer will ask questions before writing broken code. They know that clarification of requirements upfront saves hours of rework later. Your AI assistant can do the same with the right prompt structure. **By adding something as simple as _“You may ask clarifying questions before coding”_ to your prompt, the interaction goes from a one-way instruction to a collaborative conversation.** The model can then debug the requirements, not just the code. This leverages an LLM’s analytical abilities at the most valuable stage of development. ### [](#example) Example _TASK: You are helping implement a new user authentication system. Before you begin coding, identify anything that’s unclear in these requirements. Ask specific questions that would help clarify the implementation details, dependencies, or potential issues._ _REQUIREMENTS:_ * _Implement a user authentication system with password and 2FA support_ * _Should work with our existing PostgreSQL database_ * _Needs to be secure and follow best practices_ * _Should support social login options_ * _Must be scalable as we grow_ * _Implement password reset functionality- Session management should be robust_ Here’s what Claude asks if we put that task to it: _I’ll help you clarify the authentication system requirements. Here are specific questions that would help establish clearer implementation details:_ _Database integration:_ * _What user data schema do you currently have in PostgreSQL?_ * _Are there existing authentication tables we need to integrate with?_ * _Will we need to migrate existing user accounts?_ _2FA implementation:_ * _What types of 2FA are required? (SMS, email, authenticator apps, hardware keys?)_ * _Should 2FA be mandatory or optional for users?_ * _Are there compliance requirements (like NIST) we need to follow for 2FA?_ _Social login specifics:_ * _Which social login providers are required? (Google, Facebook, Apple, etc.)_ * _How should we handle account linking if a user signs up with email first, then later uses social login?_ * _What user data should we retrieve from social providers?_ _Password policies:_ * _What are the specific requirements for password complexity?_ * _What is the expected password reset flow? (Email link, security questions, etc.)_ * _Should we implement password expiration policies?_ _Session management:_ * _What is the expected session duration?_ * _Do you need support for concurrent sessions across devices?_ * _Should sessions persist across browser restarts?_ * _How should we handle session invalidation during password changes?_ _Scalability expectations:_ * _What is your current user base size and expected growth rate?_ * _Are there peak load times we should design for?_ * _Is geographical distribution of users a consideration?_ _Security requirements:_ * _Are there specific compliance standards we need to meet? (SOC2, GDPR, HIPAA, etc.)_ * _How should we handle rate limiting for login attempts?_ * _What logging requirements do you have for authentication events?_ * _Is there a need for IP-based restrictions or anomaly detection?_ _Application architecture:_ * _What is the front-end technology we’re integrating with?_ * _Will this be a stateless API or maintaining server-side sessions?_ * _Is this for a single application or should it serve as an SSO for multiple applications?_ _Clarifying these points would help create a more precise implementation plan with appropriate technology choices and development priorities._ Answering all those questions will probably take the entire context window, even before you get to code. But by encouraging AI to ask these detailed questions first, you get a much clearer picture of potential issues and edge cases. You can then work iteratively with the AI to hone the idea and ensure the most critical considerations aren’t missed. [](#iterate-with-the-ai) Iterate With the AI -------------------------------------------- Senior engineers build iteratively. Just as above, we’re talking about back-and-forth with the AI. You can also allow the model to iterate with itself. You can ask it to start by thinking about architecture, then implement components, then refine. **Breaking work into chunks—first plan, then generate, then refactor—mirrors the development workflow of experienced engineers who wouldn’t dream of writing an entire application in one sitting.** By requesting architecture diagrams, component breakdowns, or pseudocode first, you establish a solid foundation that guides subsequent development. Similarly, explicit refactoring requests after initial implementation help polish rough edges into production-quality code. ### [](#example) **Example** _TASK: We need to build a data processing pipeline that ingests CSV files of customer transactions, cleanses the data, identifies fraudulent patterns, and generates daily reports. Let’s work through this iteratively._ _PHASE 1: ARCHITECTURE PLANNING_ First, outline the high-level architecture for this pipeline. Include: * _Components and their responsibilities_ * _Data flow between components_ * _Technologies/libraries you would recommend- Key considerations for scalability, reliability, and maintainability_ _PHASE 2: COMPONENT DESIGN_ _Now that we’ve agreed on the high-level architecture, let’s design the data ingestion component in more detail:_ * _Input validation approach_ * _Error handling strategy_ * _Parsing and normalization logic_ * _Performance considerations- Potential failure modes and mitigations_ _PHASE 3: IMPLEMENTATION_ _Implement the data ingestion component based on our agreed design:_ * _File loading and validation_ * _CSV parsing with proper error handling_ * _Data normalization functions- Unit tests for the component_ _PHASE 4: REFACTORING_ _Review the implementation and suggest improvements:_ * _Code organization and structure_ * _Performance optimizations_ * _Error handling enhancements- Additional edge cases to handle_ _PHASE 5: EXTENSION_ _Now that we have a solid ingestion component, outline how we would implement the fraud detection component that will process the normalized data._ This staged approach transforms the AI from a code generator into a collaborative pair programmer that builds solutions methodically. [](#ai-can-explain-its-decisions) AI Can Explain Its Decisions -------------------------------------------------------------- Good engineers explain trade-offs, assumptions, and logic. They communicate the reasoning behind their choices. This transparency is key to effective collaboration and code quality. **Prompting LLMs to explain their approach creates a checkpoint in the development process.** You gain insight into how they interpret requirements and plan to solve the problem. This pre-implementation explanation reveals the model’s model, allowing you to catch misunderstandings before they manifest as bugs. ### [](#example) Example _TASK: We need to implement a caching layer for our product catalog API to reduce database load and improve response times. Before writing any code, explain:_ * _Your recommended caching strategy and why it’s appropriate for this use case_ * _Key technical decisions and trade-offs you’re making_ * _Potential challenges and how you plan to address them_ * _Assumptions you’re making about the current system5. Metrics you would track to validate the solution’s effectiveness_ _After explaining your approach, implement the caching layer with detailed comments explaining your implementation choices. _ _CONTEXT:_ * _Product catalog contains ~50,000 items_ * _Items are updated infrequently (1-2% change daily)_ * _API serves ~2 million requests per day_ * _Peak traffic is 5x average_ * _Current response time averages 300ms, target is <100ms_ * _Some product data is personalized based on user location/preferences_ * _Running on Kubernetes with Redis available as a caching option- Each product has ~20 attributes, average response size is 5KB_ Here is the output: _Product Catalog API Caching Strategy_ * _Recommended Caching Strategy: I recommend implementing a multi-level caching strategy with both Redis and application-level caching:_ * _Primary Cache: Redis for distributed caching with TTL (Time-To-Live)_ * _Secondary Cache: In-memory application cache for the most frequently accessed products_ * _Cache Invalidation: Event-based invalidation combined with TTL as a fallback_ _This hybrid approach is appropriate because:_ * _The product catalog has infrequent updates (only 1-2% daily change)_ * _The high request volume (2M/day) will benefit significantly from caching_ * _Having both distributed and local caches handles peak traffic (5x average) effectively_ * _The product catalog has infrequent updates (only 1-2% daily change)_ * _The high request volume (2M/day) will benefit significantly from caching_ * _Having both distributed and local caches handles peak traffic (5x average) effectively_ _Key Technical Decisions & Trade-offs_ * _Cache Granularity: Individual products vs. collections_ * _Decision: Cache both individual products and common collection queries_ * _Trade-off: More memory usage but better performance for browse scenarios_ * _Cache Keys Design:_ * _Decision: Composite keys incorporating product ID, user location, and preference hash_ * _Trade-off: More complex key management but enables personalization_ * _Invalidation Strategy:_ * _Decision: Publish-subscribe model with Redis channels for real-time invalidation_ * _Trade-off: Added complexity but ensures consistency_ * _Cache Warming:_ * _Decision: Implement a proactive cache warming strategy for popular products_ * _Trade-off: Additional system overhead but prevents cold cache issues_ * _Compression:_ * _Decision: Apply compression for cached data_ * _Trade-off: Slight CPU overhead vs. significant memory savings_ * … It continues. If you are interested, the final implementation the LLM suggested is in this gist: By forcing the AI to think through the solution holistically before writing code, you make problems visible before implementation begins. [](#ai-can-say-i-dont-know) AI Can Say “I Don’t Know” ----------------------------------------------------- Good engineers flag unknowns and admit limitations. They recognize that acknowledging uncertainty is a strength, not a weakness. **Prompting the LLM to annotate guesses or assumptions creates a layer of transparency in your AI code.** Just as senior developers distinguish between verified facts and educated guesses in their work, this practice helps you separate reliable outputs from speculative ones. When the model clearly marks areas of uncertainty, you can focus additional verification efforts where they’re most needed. This targeted validation process mirrors how experienced teams manage risk by concentrating scrutiny on the least certain components. ### [](#example) Example _TASK: You’re designing a recommendation algorithm for an e-commerce platform. Based on the information provided:_ * _Propose a suitable recommendation approach_ * _Outline how you would implement it_ * _Identify any areas where you’re uncertain or would need more information_ * _Clearly mark any assumptions you’re making_ _CONTEXT:_ * _Platform sells fashion items (clothing, accessories)_ * _Has approximately 200,000 active monthly users_ * _Database contains 2 years of purchase history_ * _We have user browsing data and purchase history_ * _Currently no recommendation system in place_ * _Tech stack includes PostgreSQL, Python backend, React frontend_ _After your solution, explicitly list any parts where:_ * _You’re making educated guesses rather than confident assertions_ * _You would need additional information to make a better recommendation- There are multiple valid approaches and you’re unsure which is optimal_ The model returns the implementation proposal, but appends this to the end: _\## Uncertain Areas and Information Needs_ _\### Educated Guesses Rather Than Confident Assertions_ * _The optimal weighting between collaborative filtering, content-based filtering, and trend-based recommendations (currently proposed as 60/30/10)_ * _The ideal frequency for model retraining (suggested daily, but could be weekly)_ * _The impact of seasonality on this specific fashion platform’s recommendations_ * _The degree to which visual similarity (vs. metadata similarity) drives purchases_ _\### Additional Information Needs_ * _Conversion rates and funnel metrics to establish a baseline_ * _Details about product taxonomy and attributes_ * _Information about customer segments and their purchasing behaviors_ * _Returns data and reasons for returns_ * _Marketing calendar and promotional events that might affect recommendation relevance_ * _Geographic distribution of users (for seasonal adjustments)_ * _User demographics to better understand preference patterns_ * _Inventory constraints that might affect recommendation strategy_ _\### Multiple Valid Approaches_ * _Model Architecture:_ * _Matrix factorization vs. neural collaborative filtering vs. graph-based methods_ * _Explicit vs. implicit feedback emphasis_ * _Batch learning vs. online learning_ * _Cold Start Handling:_ * _Content-based only vs. popularity-based vs. quick questionnaire_ * _Category-based defaults vs. trending items_ * _Recommendation Diversity:_ * _How to balance similarity with discovery_ * _Whether to explicitly model diversity or let it emerge naturally_ * _Deployment Strategy:_ * _Full system at once vs. incremental rollout by page/feature- Single model vs. ensemble of specialized models for different contexts_ By encouraging the AI to identify uncertainties and assumptions, you get a much more honest assessment of its solution and can focus on resolving the most important open questions. [](#ai-should-give-you-maintainable-idiomatic-code) AI Should Give You Maintainable, Idiomatic Code --------------------------------------------------------------------------------------------------- It’s not just about working—it’s about doing it the right way. Senior engineers write code that follows best practices, conforms to team standards, and can be maintained by others. **Just as experienced developers prioritize readability and maintainability over clever hacks, explicitly prompting for idiomatic code ensures you receive solutions that integrate with existing codebases.** This approach yields code that your team can understand, extend, and maintain long after the initial implementation. ### [](#example) Example Here, we ask not just for TypeScript, but a specific version, following a particular style guide, and with specific functionality: _TASK: Implement a service in TypeScript that fetches and processes user activity data. The service will be part of a larger application that tracks user engagement metrics._ _REQUIREMENTS:_ * _The service should fetch user activity data from a REST API_ * _It should process the data to calculate engagement metrics_ * _It should cache results to minimize API calls_ * _It should handle errors gracefully with proper logging_ _CODING STANDARDS:_ * _Use modern TypeScript (v4.5+) with strict type checking_ * _Follow Airbnb style guide conventions_ * _Use functional programming patterns where appropriate_ * _Prefer immutability and pure functions_ * _Use async/await for asynchronous operations_ * _Include comprehensive error handling_ * _Add complete JSDoc documentation for public methods_ * _Write code that follows SOLID principles_ * _Include unit tests using Jest_ _TECHNICAL CONTEXT:_ * _The application uses Axios for HTTP requests_ * _We use Redis for caching through the ‘ioredis’ client_ * _Logging is done via Winston logger_ * _The application runs in a Node.js environment_ * _TypeScript configuration has strict mode enabled_ * _Please provide a complete, production-ready implementation with proper structure, error handling, and tests. Include explanatory comments and documentation._ This simple prompt produced so much code that we can’t add it all here. Instead, [this repo](https://github.com/argotdev/user-activity-service) shows the service, types, factory function, tests, and docs. Claude produced everything from this single prompt (do you notice the obvious mistake?).  By specifying detailed coding standards and patterns, you get idiomatic code that follows team conventions and best practices, making it much more maintainable and reliable. [](#build-a-better-mental-model) Build a Better Mental Model ------------------------------------------------------------ You get out what you put in. If you treat AI like a junior developer, you get rushed solutions that miss critical details, create technical debt, and require extensive rework. The AI will follow instructions literally without raising concerns, leading to exactly the hallucinations, slop, and edge cases described earlier. But if you treat it like a senior teammate–setting context, reviewing work, iterating, and asking for deeper thinking–you’ll tap into LLMs’ incredible potential. This is a little more work for you, but it will yield much better results. The key insight is that AI isn’t magic—it’s a tool that works best with structured input and collaborative iteration. Treating AI like a senior developer rather than a junior one sets it up for success and maximizes its value to your development process. * * * _Neon is a serverless Postgres database used by v0 and Replit Agent. It also works like a charm with AI IDEs like Cursor [via its MCP Server](https://neon.tech/guides/cursor-mcp-neon) . [Sign up for Neon](https://console.neon.tech/signup)  (we have a Free Plan) and start building._ Share: More from Neon -------------- * [![State of AI 2025: How Developers Are Adopting AI Coding Tools](/_next/image?url=https%3A%2F%2Fneondatabase.wpengine.com%2Fwp-content%2Fuploads%2F2025%2F04%2FScreenshot-2025-04-23-at-11.35.04%E2%80%AFAM.png&w=3840&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc)](/blog/state-of-ai-survey-2025) [AI](/blog/category/ai) Apr 23, 2025 [State of AI 2025: How Developers Are Adopting AI Coding Tools\ =============================================================\ \ ![Carlota Soto](/_next/image?url=https%3A%2F%2Fneondatabase.wpengine.com%2Fwp-content%2Fuploads%2F2024%2F02%2Fcarlota.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc)\ \ Carlota Soto](/blog/state-of-ai-survey-2025) * [![Announcing Neon Snapshots: A Smoother Path to Recovery](/_next/image?url=https%3A%2F%2Fneondatabase.wpengine.com%2Fwp-content%2Fuploads%2F2025%2F04%2Fneon-snapshot-cover.jpg&w=3840&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc)](/blog/announcing-neon-snapshots-a-smoother-path-to-recovery) [Engineering](/blog/category/engineering) Apr 23, 2025 [Announcing Neon Snapshots: A Smoother Path to Recovery\ ======================================================\ \ ![Bryan Clark](/_next/image?url=https%3A%2F%2Fneondatabase.wpengine.com%2Fwp-content%2Fuploads%2F2024%2F04%2FBryan-Clark.jpg&w=64&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc)\ \ Bryan Clark](/blog/announcing-neon-snapshots-a-smoother-path-to-recovery) --- # Neon Docs - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) Neon Docs ========= Neon is a serverless Postgres platform designed to help you build reliable and scalable applications faster. We separate compute and storage to offer modern developer features such as autoscaling, branching, instant restore, and more. Get started today with our [generous free plan](https://console.neon.tech) . Manage Neon from Cursor ✨ ------------------------- Manage your Neon Postgres databases from Cursor and other AI tools using simple, conversational commands with Neon's MCP Server. [Learn how](/docs/ai/connect-mcp-clients-to-neon) ➡️ Neon AI chat assistants ----------------------- * [Docs](/ai-chat) * [GitHub Copilot](https://github.com/marketplace/neon-database) * [VS Code](https://marketplace.visualstudio.com/items?itemName=buildwithlayer.neon-integration-expert-15j6N) * [Discord](https://discord.com/channels/1176467419317940276/1222626436502782013) [](#get-started) Get started ---------------------------- 1. [1.\ \ ### Playing with Neon\ \ Sign up for free and learn the basics of database branching with Neon](/docs/get-started-with-neon/signing-up) 2. [2.\ \ ### Connect Neon to your stack\ \ Connect Neon to the platform, language, ORM and other tools in your tech stack](/docs/get-started-with-neon/connect-neon) 3. [3.\ \ ### Branching workflows\ \ Add branching to your CI/CD automation](/docs/get-started-with-neon/workflow-primer) 4. [4.\ \ ### Get ready for production\ \ Key features to get you production ready](/docs/get-started-with-neon/production-checklist) [](#quickstarts) Quickstarts ---------------------------- * [![drizzle logo](/images/technology-logos/drizzle.svg)\ \ ### Drizzle\ \ Learn how to use Drizzle ORM with your Neon Postgres database (Drizzle docs)](/docs/guides/drizzle) * [![react logo](/images/technology-logos/react.svg)\ \ ### React\ \ Build powerful and interactive user interfaces with React using Neon as your database](/docs/guides/react) * [![node-js logo](/images/technology-logos/node-js.svg)\ \ ### Node.js\ \ Quickly add authentication and user management to your Node.js application](/docs/guides/node) Show more [](#explore-the-neon-docs) Explore the Neon Docs ------------------------------------------------ * [### Connect\ \ Learn how to connect to a Serverless Postgres database from any application](/docs/connect/connect-intro) * [### Import data\ \ Load your data into a Postgres database hosted by Neon](/docs/import/import-intro) * [### AI & embeddings\ \ Build and scale transformative LLM applications with vector storage and similarity search.](/docs/ai/ai-intro) * [### Branching\ \ Learn to optimize development workflows with database branching](/docs/guides/branching-intro) * [### Postgres extensions\ \ Level up your database with our many supported Postgres extensions](/docs/extensions/extensions-intro) * [### Neon CLI Reference\ \ Manage Neon directly from the terminal with the Neon CLI](/docs/reference/neon-cli) [](#join-the-community) Join the community ------------------------------------------ If you have questions about Neon or Postgres, reach out to Neon community members and developers on our [Discord Server](https://discord.com/invite/92vNTzKDGp) . Welcome to the Neon Discord Server! ----------------------------------- [Join server](https://discord.gg/92vNTzKDGp) ![](/_next/static/svgs/358145d2e0f7564bac49c5a87a09579a.svg)![](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.a8e8407a.png&w=640&q=90&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) [NextOur mission](/docs/get-started-with-neon/why-neon) Last updated on March 17, 2025 Was this page helpful? YesNo Thank you for your feedback! [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/introduction.md) ### Neon AI chat assistants * [Docs](/ai-chat) * [GitHub Copilot](https://github.com/marketplace/neon-database) * [VS Code](https://marketplace.visualstudio.com/items?itemName=buildwithlayer.neon-integration-expert-15j6N) * [Discord](https://discord.com/channels/1176467419317940276/1222626436502782013) --- # Neon AI Chat [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Back to Docs](/docs/introduction) [Ask Neon AI](/ai-chat) Neon AI Chat ============ --- # Connect to Neon - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Connect Connect to Neon =============== Everything you need to know about connecting to Neon Find detailed information and instructions about connecting to Neon from different clients and applications, troubleshooting connection issues, connection pooling, and more. For integrating Neon with different frameworks, languages, and platforms, refer to our [Guides](/docs/guides/guides-intro) documentation. [](#connect-from-clients-and-applications) Connect from clients and applications -------------------------------------------------------------------------------- Learn how to establish a connection to Neon from any application. * [### Choose a driver and connection type\ \ How to select the right driver and connection type for your application](/docs/connect/choose-connection) * [### Connect from any app\ \ Learn about connection strings and how to connect to Neon from any application](/docs/connect/connect-from-any-app) * [### Neon serverless driver\ \ Connect to Neon from serverless environments over HTTP or WebSockets](/docs/serverless/serverless-driver) * [### Connect a GUI application\ \ Learn how to connect to a Neon database from a GUI application](/docs/connect/connect-postgres-gui) * [### Connect with psql\ \ Connect with psql, the native command-line client for Postgres](/docs/connect/query-with-psql-editor) * [### Passwordless auth\ \ Connect without a password using Neon's psql passwordless auth feature](/docs/connect/passwordless-connect) [](#connect-from-frameworks-and-languages) Connect from frameworks and languages -------------------------------------------------------------------------------- Learn how to connect to Neon from different frameworks and languages. * [### Connect from various frameworks\ \ Find detailed instructions for connecting to Neon from various frameworks](/docs/get-started-with-neon/frameworks) * [### Connect from various languages\ \ Find detailed instructions for connecting to Neon from various languages](/docs/get-started-with-neon/languages) [](#troubleshoot-connection-issues) Troubleshoot connection issues ------------------------------------------------------------------ Troubleshoot and resolve common connection issues. * [### Connection errors\ \ Learn how to resolve commonly-encountered connection errors](/docs/connect/connection-errors) * [### Connect latency and timeouts\ \ Learn about strategies for managing connection latency and timeouts](/docs/connect/connection-latency) [](#secure-connections) Secure connections ------------------------------------------ Ensure the integrity and security of your connections to Neon. * [### Connect to Neon securely\ \ Learn how to connect to Neon securely using SSL/TLS encrypted connections](/docs/connect/connect-securely) * [### Avoid MME attacks in Postgres 16\ \ Learn how the psql client in Postgres 16 makes it simple to connect securely](https://neon.tech/blog/avoid-mitm-attacks-with-psql-postgres-16) [](#connection-pooling) Connection pooling ------------------------------------------ Optimize your connections by enabling connection pooling. * [### Connection pooling in Neon\ \ Learn how to enable connection pooling to support up to 10,000 concurrent connections](/docs/connect/connection-pooling) * [### Connection pooling with Prisma\ \ Learn about connecting from Prisma to Neon from serverless functions](/docs/guides/prisma#connect-from-serverless-functions) [PreviousSymfony](/docs/guides/symfony) [NextChoosing connections](/docs/connect/choose-connection) Last updated on August 10, 2024 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Connect from clients and applications](#connect-from-clients-and-applications) * [Connect from frameworks and languages](#connect-from-frameworks-and-languages) * [Troubleshoot connection issues](#troubleshoot-connection-issues) * [Secure connections](#secure-connections) * [Connection pooling](#connection-pooling) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/connect/connect-intro.md) --- # Why Neon? - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Why Neon? Why Neon? ========= Neon is Serverless Postgres built for the cloud Looking back at Neon's debut blog post, [SELECT ’Hello, World’](https://neon.tech/blog/hello-world) , the fundamental reasons for **Why Neon** remain the same: * **To build the best Postgres experience in the cloud** This is still our core mission today. It was clear to us then, as it is now, that database workloads are shifting to the cloud — and no one wants to manage a database themselves. * **In an ever-changing technology stack, we believe Postgres is here to stay** Just like the Linux operating system or Git version control, we believe Postgres is the default choice for a relational database system. That’s why all of the major platforms like AWS, Azure, Google Cloud, Digital Ocean, and many newcomers to this space offer Postgres as a service. * **An idea that a modern Postgres cloud service can be designed differently** We call this approach _separation of storage and compute_, which lets us architect the service around performance, reliability, manageability, and cost-efficiency. * **The belief that our architecture can provide a better Developer Experience (DevX)** Features such as autoscaling, branching, time travel, instant provisioning, and instant restore improve the developer experience by allowing quick environment setup, efficient developer workflows, and immediate database availability. These are Neon's reasons, but given the many _database-as-a-service_ options available today, let's take a look at the reasons why **you** should choose Neon: [](#neon-is-postgres) Neon is Postgres -------------------------------------- **Postgres is the world's most popular open-source database.** From its beginning as a [DARPA-sponsored project at Berkeley](https://www.postgresql.org/docs/current/history.html) , Postgres has fostered an ever-growing community and is a preferred database among developers because of its performance, reliability, extensibility, and support for features like ACID transactions, advanced SQL, and NoSQL/JSON. Neon supports all of the latest Postgres versions and numerous [Postgres extensions](/docs/extensions/extensions-intro) . **If your application runs on Postgres, it runs on Neon**. If it doesn't run on Postgres, [sign up](https://console.neon.tech/signup) for a Free Plan account, join our [Discord server](https://discord.gg/92vNTzKDGp) , and start the journey with us. [](#neon-is-serverless) Neon is serverless ------------------------------------------ **A serverless architecture built for performance, reliability, manageability, and cost efficiency** Neon's [architecture](/docs/introduction/architecture-overview) separates compute from storage, which enables serverless features like instant provisioning, [autoscaling](/docs/get-started-with-neon/production-readiness#autoscaling) , [scale to zero](/docs/get-started-with-neon/production-readiness#scale-to-zero) , and more. Separating compute from storage refers to an architecture where the database computation processes (queries, transactions, etc.) are handled by one set of resources (compute), while the data itself is stored on a separate set of resources (storage). This design contrasts with traditional architectures where compute and storage are tightly coupled on the same server. In Neon, Postgres runs on a compute, and data (except for what's cached in local compute memory) resides on Neon's storage layer. Separation of compute and storage allows these resources to be scaled independently. You can adjust for processing power or storage capacity as needed without affecting the other. This approach is also cost-efficient. The ability to scale resources independently means you can benefit from the lower cost of storage compared to compute or avoid paying for additional storage when you only require extra processing power. Decoupling compute and storage also improves availability and durability, as data remains accessible and safe, even if a compute fails. [Read more about the benefits of Neon's serverless architecture](/docs/introduction/serverless) and how it supports database-per-user architectures, variable workloads, database branching workflows, and [AI agents](https://neon.tech/use-cases/ai-agents) . #### Did you know? Neon's autoscaling feature instantly scales your compute and memory resources. **No manual intervention or restarts are required.** [](#neon-is-fully-managed) Neon is fully managed ------------------------------------------------ **Leave the database administrative, maintenance, and scaling burdens to us.** Being a fully managed service means that Neon provides high availability without requiring users to handle administrative, maintenance, or scaling burdens associated with managing a database system. This approach allows developers to focus more on developing applications and less on the operational aspects of database management. Neon takes care of the complexities of scaling, backups, maintenance, and ensuring availability, enabling developers to manage their data without worrying about the underlying infrastructure. [](#neon-is-open-source) Neon is open source -------------------------------------------- **Neon is developed under an Apache 2.0 license.** Neon is not the first to offer separation of storage and compute for Postgres. AWS Aurora is probably the most famous example — but it's proprietary and tied to AWS’s internal infrastructure. We believe we have an opportunity to define the standard for cloud Postgres. We carefully designed our storage, focusing on cloud independence, performance, manageability, DevX, and cost. We chose the most permissive open-source license, Apache 2.0, and invited the world to participate. You can already build and run your own self-hosted instance of Neon. Check out our [neon GitHub repository](https://github.com/neondatabase) and the [#self-hosted](https://discord.com/channels/1176467419317940276/1184894814769127464) channel on our Discord server. [](#neon-doesnt-lock-you-in) Neon doesn't lock you in ----------------------------------------------------- **As a true Postgres platform, there's no lock-in with Neon.** Building on Neon is building on Postgres. If you are already running Postgres, getting started is easy. [Import your data](/docs/import/import-intro) and [connect](/docs/connect/connect-intro) . Migrating from other databases like MySQL or MongoDB is just as easy. If you need to move data, you won't have to tear apart your application to remove proprietary application layers. Neon is pro-ecosystem and pro-integration. We encourage you to build with the frameworks, platforms, and services that best fit your requirements. Neon works to enable that. Check out our ever-expanding collection of [framework](/docs/get-started-with-neon/frameworks) , [language](/docs/get-started-with-neon/languages) , and [integration](/docs/guides/integrations) guides. [](#who-should-use-neon) Who should use Neon? --------------------------------------------- **You. And we're ready to help you get started.** Neon is designed for a wide range of users, from individual developers to enterprises, seeking modern, serverless Postgres capabilities. It caters to those who need a fully managed, scalable, and cost-effective database solution. Key users include: * **Individual developers** looking for a fast and easy way to set up a Postgres database without the hassle of installation or configuration. Neon's Free Plan makes it easy to get started. [Free Plan](/docs/introduction/plans#free-plan) users get access to all regions and features like connection pooling, project collaboration, and branching. When you are ready to scale, you can easily upgrade your account to a paid plan for more computing power, storage, and advanced features. #### Neon's Free Plan is here to stay Neon's Free Plan is a fundamental part of our commitment to users. Our architecture, which separates storage and compute, enables a sustainable Free Plan. You can build your personal project or PoC with confidence, knowing that our Free Plan is here to stay. [Learn more about our Free Plan from Neon's CEO](https://twitter.com/nikitabase/status/1758639571414446415) . * **Teams and organizations** that aim to enhance their development workflows with the ability to create database branches for testing new features or updates, mirroring the branching process used in code version control. * **Enterprises** requiring scalable, high-performance database solutions with advanced features like autoscaling, scale to zero, instant restore, and logical replication. Enterprises can benefit from custom pricing, higher resource allowances, and enterprise-level support to meet their specific requirements. * **AI agents** that need to rapidly provision Postgres databases, execute SQL queries, and efficiently manage Neon infrastructure. With one-second provision times, scale-to-zero compute, and agent-friendly client interfaces, Neon enables AI agents to manage database fleets at scale while keeping costs low. AI agents are on track to surpass humans in the number of databases created on the Neon platform. [Learn more about this use case](https://neon.tech/use-cases/ai-agents) . In summary, Neon is built for anyone who requires a Postgres database and wants to benefit from the scalability, ease of use, cost savings, and advanced DevX capabilities provided by Neon's serverless architecture. [](#neon-makes-it-easy-to-get-started-with-postgres) Neon makes it easy to get started with Postgres ---------------------------------------------------------------------------------------------------- **Set up your Postgres database in seconds.** 1. [Log in](https://console.neon.tech/signup) with an email address, Google, or GitHub account. 2. Provide a project name and database name, and select a region. 3. Click **Create Project**. Neon's architecture allows us to spin up a Postgres database almost instantly and provide you with a database URL, which you can plug into your application or database client. postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname Additionally, after signing up, we land you on your project dashboard, where you'll find connection snippets for various frameworks, languages, and platforms. ![Next.js connection snippet from the Connection details widget on the Neon Dashboard](/_next/image?url=%2Fdocs%2Fconnect%2Fcode_connection_examples.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) If you are not quite ready to hook up an application, you can explore Neon from the console. Create the `playing_with_neon` table using the Neon [SQL Editor](/docs/get-started-with-neon/query-with-neon-sql-editor) , run some queries, or create a database branch. Initially, you'll be signed up for Neon's [Free Plan](/docs/introduction/plans#free-plan) , but you can easily upgrade to one of our [paid plans](/docs/introduction/plans) when you're ready. Are you ready? -------------- After signing up, remember to join our active Discord community, where you'll find Neon users and team members ready to help. [Sign up](https://console.neon.tech/signup) [NextDeveloper experience with Neon](/docs/get-started-with-neon/dev-experience) Last updated on February 8, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Neon is Postgres](#neon-is-postgres) * [Neon is serverless](#neon-is-serverless) * [Neon is fully managed](#neon-is-fully-managed) * [Neon is open source](#neon-is-open-source) * [Neon doesn't lock you in](#neon-doesnt-lock-you-in) * [Who should use Neon?](#who-should-use-neon) * [Neon makes it easy to get started with Postgres](#neon-makes-it-easy-to-get-started-with-postgres) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/get-started-with-neon/why-neon.md) --- # Neon data migration guides - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Migrate to Neon Neon data migration guides ========================== Learn how to migrate data to Neon Postgres from different database providers and sources Find instructions for migrating data from Postgres, CSV, other Neon projects, and other database providers. For near-zero downtime data migrations from other Postgres providers, consider using logical replication. Additionally, if you're new to Neon and want to try it out, our sample data guide provides datasets for exploration and testing. #### Can We Help with Your Migration? If you're planning to migrate a production workload to Neon, let us know—we'll connect you with an expert from our team. You can reach out to us [here](https://neon.tech/migration-assistance) . [](#data-migration-guides) Data migration guides ------------------------------------------------ * [### Import Data Assistant\ \ Move your existing database to Neon using our guided migration tool](/docs/import/import-data-assistant) * [### Migrate with pg\_dump and pg\_restore\ \ Migrate data from another Postgres database using pg\_dump and pg\_restore](/docs/import/migrate-from-postgres) * [### Migrate from another Neon project\ \ Migrate data from another Neon project for Postgres version, region, or account migration](/docs/import/migrate-from-neon) * [### Migrate schema only\ \ Migrate only the schema from a Postgres database with pg\_dump and pg\_restore](/docs/import/migrate-schema-only) * [### Import data from CSV\ \ Import data from a CSV file using the psql command-line utility](/docs/import/import-from-csv) * [### Migrate from Firebase Firestore\ \ Migrate data from Firebase Firestore to Neon Postgres using a custom Python script](/docs/import/migrate-from-firebase) * [### Migrate from Heroku\ \ Migrate data from a Heroku Postgres database to Neon Postgres using the Heroku CLI](/docs/import/migrate-from-heroku) * [### Migrate with AWS DMS\ \ Migrate data from another database source to Neon using the AWS Data Migration Service](/docs/import/migrate-aws-dms) * [### Migrate from Azure\ \ Migrate from an Azure Database for PostgreSQL to Neon Postgres](/docs/import/migrate-from-azure-postgres) * [### Migrate from Digital Ocean\ \ Migrate data from Digital Ocean Postgres to Neon Postgres with pg\_dump and pg\_restore](/docs/import/migrate-from-digital-ocean) * [### Import sample data\ \ Import one of several sample datasets for exploration and testing](/docs/import/import-sample-data) * [### Migrate from MySQL\ \ Migrate your MySQL data to Neon Postgres using pgloader.](/docs/import/migrate-mysql) * [### Migrate from Render\ \ Migrate data from Render to Neon Postgres with pg\_dump and pg\_restore](/docs/import/migrate-from-render) * [### Migrate from Supabase\ \ MIgrate data from Supabase to Neon Postgres with pg\_dump and pg\_restore](/docs/import/migrate-from-supabase) * [### Migrate with pgcopydb\ \ Migrate data from another Postgres database using pgcopydb for parallel processing](/docs/import/pgcopydb) [](#use-logical-replication-for-near-zero-downtime-data-migrations) Use logical replication for near-zero downtime data migrations ---------------------------------------------------------------------------------------------------------------------------------- Postgres logical replication in Neon provides an efficient way to migrate data from other Postgres providers with minimal downtime. By replicating data in real-time, this method allows you to transition your applications to Neon without interrupting your services. Please refer to our logical replication guides for instructions. * [![alloydb logo](/images/technology-logos/alloydb.svg)\ \ ### AlloyDB\ \ Replicate data from AlloyDB to Neon](/docs/guides/logical-replication-alloydb) * [![aws-rds logo](/images/technology-logos/aws-rds.svg)\ \ ### Aurora\ \ Replicate data from Aurora to Neon](/docs/guides/logical-replication-aurora-to-neon) * [![google-cloud-sql logo](/images/technology-logos/google-cloud-sql.svg)\ \ ### Cloud SQL\ \ Replicate data from Cloud SQL to Neon](/docs/guides/logical-replication-cloud-sql) * [![postgresql logo](/images/technology-logos/postgresql.svg)\ \ ### PostgreSQL to Neon\ \ Replicate data from PostgreSQL to Neon](/docs/guides/logical-replication-postgres-to-neon) * [![aws-rds logo](/images/technology-logos/aws-rds.svg)\ \ ### AWS RDS\ \ Replicate data from AWS RDS PostgreSQL to Neon](/docs/guides/logical-replication-rds-to-neon) * [![supabase logo](/images/technology-logos/supabase.svg)\ \ ### Supabase\ \ Replicate data from Supabase to Neon](/docs/guides/logical-replication-supabase-to-neon) * [![azure logo](/images/technology-logos/azure.svg)\ \ ### Azure PostgreSQL\ \ Replicate data from Azure PostgreSQL to Neon](/docs/import/migrate-from-azure-postgres) [PreviousLatency and timeouts](/docs/connect/connection-latency) [NextImport Data Assistant](/docs/import/import-data-assistant) Last updated on April 21, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Data migration guides](#data-migration-guides) * [Use logical replication for near-zero downtime data migrations](#use-logical-replication-for-near-zero-downtime-data-migrations) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/import/migrate-intro.md) --- # Neon architecture - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Architecture Neon architecture ================= Neon architecture is based on the separation of compute and storage and is orchestrated by the Neon Control Plane, which manages cloud resources across both storage and compute. A Neon compute runs Postgres, and storage is a multi-tenant key-value store for Postgres pages that is custom-built for the cloud. ![Neon architecture diagram](/_next/image?url=%2Fdocs%2Fintroduction%2Fneon_architecture_5.jpg&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Neon storage consists of three main components: Safekeepers, Pageservers, and cloud object storage. Safekeepers are responsible for durability of recent updates. Postgres streams [Write-Ahead Log (WAL)](/docs/reference/glossary#wal) to the Safekeepers, and the Safekeepers store the WAL durably until it has been processed by the Pageservers and uploaded to a cloud object store. Pageservers are responsible for serving read requests. To do that, Pageservers process the incoming WAL stream into a custom storage format that makes all [page](/docs/reference/glossary#page) versions easily accessible. Pageservers also upload data to cloud object storage, and download the data on demand. Safekeepers can be thought of as an ultra-reliable write buffer that holds the latest data until it is processed and uploaded to cloud storage. Safekeepers implement the Paxos protocol for reliability. Pageservers also function as a read cache for cloud storage, providing fast random access to data pages. [](#durability) Durability -------------------------- Durability is at the core of Neon's architecture. As described earlier, incoming WAL data is initially stored across multiple availability zones in a [Paxos](https://en.wikipedia.org/wiki/Paxos_(computer_science)) cluster before being uploaded to a cloud object store, such as [Amazon S3](https://aws.amazon.com/s3/) (99.999999999% durability), both in raw WAL and materialized form. Additional copies are maintained across Pageservers to enhance the read performance of frequently accessed data. Consequently, there are always multiple copies of your data in Neon, ensuring durability. [](#archive-storage) Archive storage ------------------------------------ Archive storage in Neon, which enables [branch archiving](/docs/guides/branch-archiving) on the Free Plan, optimizes storage resources by offloading data that's not being used. As described above, Neon’s architecture includes Safekeepers, Pageservers, and cloud object storage. In this setup, the Pageservers are responsible for processing and uploading data to cloud object storage as soon as it's written. When a branch is archived, it does not involve moving data; instead, the branch's data is simply evicted from the Pageserver, freeing up Pageserver storage. This approach ensures that while archived data is readily available on demand in cost-efficient object storage, it's no longer taking up space in the more performant storage used by Neon's Pageservers. [PreviousSample data](/docs/import/import-sample-data) [NextArchitecture](/docs/introduction/autoscaling-architecture) Last updated on November 21, 2024 Was this page helpful? YesNo Thank you for your feedback! [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/introduction/architecture-overview.md) --- # Playing with Neon - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Getting Started Playing with Neon ================= Sign up for free and learn the basics of database branching with Neon ### What you will learn: * How to view and modify data in the console * Create an isolated database copy per developer * Reset your branch to production when ready to start new work ### Related topics * [About branching](/docs/introduction/branching) * [Branching workflows](/docs/get-started-with-neon/workflow-primer) * [Connect Neon to your stack](/docs/get-started-with-neon/connect-neon) This tutorial walks you through your first steps using Neon as your Postgres database. You'll explore the Neon object hierarchy and learn how database branching can simplify your development workflow. [](#about-branching) About branching ------------------------------------ Each [branch](/docs/introduction/branching) is a fully-isolated copy of its parent. We suggest creating a long-term branch for each developer on your team to maintain consistent connection strings. You can reset your development branch to production whenever needed. After signing up, you'll start with two branches: * A `production` branch (the default branch) intended for your production workload, configured with a larger compute size (1-4 CU) * A `development` branch (created as a child of production) that you can use for local development, configured with a smaller compute size (0.25-1 CU) You can change these sizes at any time, but these are meant to align with typical usage, where production will need more compute than your less active development branches. 1. [](#sign-up) Sign up -------------------- If you're already signed up or coming to Neon from **Azure**, you can skip ahead to [Step 2](/docs/get-started-with-neon/signing-up#step-2-onboarding-in-the-neon-console) . If you haven't signed up yet, you can sign up for free here: [https://console.neon.tech/signup](https://console.neon.tech/signup) Sign up with your email, GitHub, Google, or other partner account. For information about what's included with the free plan, see [Neon Free Plan](/docs/introduction/plans#free-plan) . For information about Neon's paid options, see [Neon Plans](/docs/introduction/plans) . ![sign_up](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fsign_up_reduced.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) 2. [](#onboarding-in-the-neon-console) Onboarding in the Neon Console ------------------------------------------------------------------ After you sign up, you are guided through some onboarding steps that ask you to create a **Project**. ![onboarding](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fonboarding.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) The steps should be self-explanatory, but it's important to understand a few key points: * **In Neon, everything starts with the _Project_** It is the top-level container that holds your branches, databases, and roles. Typically, you should create a project for each repository in your application. This allows you to manage your database branches just like you manage your code branches: a branch for production, staging, development, new features, previews, and so forth. * **We create two branches for you** * `production` is the default (primary) branch and hosts your database, role, and a compute that you can connect your application to * `development` is created as a child branch of production for your development work At this point, if you want to just get started connecting Neon to your toolchain, go to [Day 2 - Connecting Neon to your tools](/docs/get-started-with-neon/connect-neon) . Or if you want a more detailed walkthrough of some of our key console and branching features, let's keep going. 3. [](#add-sample-data) Add sample data ------------------------------------ Let's get familiar with the **SQL Editor**, where you can run queries against your databases directly from the Neon Console, as well as access more advanced features like [Time Travel](/docs/guides/time-travel-assist) and [Explain and Analyze](/docs/get-started-with-neon/query-with-neon-sql-editor#explain-and-analyze) . From the Neon Console, use the sidebar navigation to open the **SQL Editor** page. Notice that your default branch `production` is already selected, along with the database created during onboarding, `neondb`. ![Neon SQL Editor](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fsql_editor.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) The first time you open the SQL Editor for a new project, the editor includes placeholder SQL commands to create and populate a new sample table called `playing_with_neon`. For this tutorial, go ahead and create this sample table: click **Run**. Every query you run in the SQL Editor is automatically saved with an AI-generated description, making it easy to find and reference your work later. For example, the sample table creation above will be saved with a description like "create and populate sample table in Neon". You can view your query history anytime by clicking the **History** button in the SQL Editor. Or if you want to add the table from the command line and you already have `psql` installed: CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL); INSERT INTO playing_with_neon(name, value) SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i); Your default branch `production` now has a table with some data. 4. [](#try-the-ai-assistant) Try the AI Assistant ---------------------------------------------- Now that you have some sample data, let's explore how the AI Assistant can help you write SQL queries using natural language prompts. From the SQL Editor, click the **AI Assistant** button in the top-right corner and try a few prompts: * _Add three more rows to the playing\_with\_neon table with tech company names_ * _Show me the highest value in the table_ * _Calculate the average value grouped by the first letter of the name_ ![Neon SQL Editor AI Assistant](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fsql_assistant.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Each query you run is automatically saved with an AI-generated description, making it easy to find and reuse queries later. For example, when you ask the AI Assistant to add company data, you should see a response like: -- Text to SQL original prompt: -- Add three more rows to the playing_with_neon table with tech company names INSERT INTO public.playing_with_neon (name, value) VALUES ('Google', 1000.5), ('Apple', 1200.75), ('Microsoft', 950.25); With the description: "Add tech companies to playing\_with\_neon table" Learn more about AI features in the [SQL Editor documentation](/docs/get-started-with-neon/query-with-neon-sql-editor#ai-features) . 5. [](#view-and-modify-data-in-the-console) View and modify data in the console ---------------------------------------------------------------------------- Now that you have some data to play with, let's take a look at it on the **Tables** page in the Neon Console. The **Tables** page, powered by [Drizzle Studio](https://orm.drizzle.team/drizzle-studio/overview) , provides a visual interface for exploring and modifying data directly from the console. The integration with Drizzle Studio provides the ability to add, update, and delete records, filter data, add or remove columns, drop or truncate tables, and export data in `.json` and `.csv` formats. ![Tables page Drizzle integration](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Ftables_drizzle.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) For a detailed guide on how to interact with your data using the **Tables** page, visit [Managing your data with interactive tables](/docs/guides/tables) . 6. [](#working-with-your-development-branch) Working with your development branch ------------------------------------------------------------------------------ Your project comes with a `development` branch that's an isolated copy of your `production` branch. Let's learn how to use the Neon CLI to manage branches and make some schema changes in your development environment. 1. **Install CLI with Brew or NPM** Depending on your system, you can install the Neon CLI using either Homebrew (for macOS) or NPM (for other platforms). * For macOS using Homebrew: brew install neonctl * Using NPM (applicable for all platforms that support Node.js): npm install -g neonctl 2. **Authenticate with Neon** The `neon auth` command launches a browser window where you can authorize the Neon CLI to access your Neon account. neon auth ![neon auth](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fneonctl_auth.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) 3. **View your branches** neon branches list This command shows your existing branches, including the `production` and `development` branches. 7. [](#make-some-sample-schema-changes) Make some sample schema changes -------------------------------------------------------------------- First, let's make sure our development branch is in sync with production. This ensures we're starting from the same baseline: neon branches reset development --parent Now that our development branch matches production, we can make some changes. The `playing_with_neon` table from production is now available in your `development` branch, and we'll modify its schema and add new data to demonstrate how branches can diverge. You can use the [Neon SQL Editor](/docs/get-started-with-neon/query-with-neon-sql-editor) for this, but let's demonstrate how to connect and modify your database from the terminal using `psql`. If you don't have `psql` installed already, follow these steps to get set up: MacLinuxWindows brew install libpq echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc source ~/.zshrc With `psql` available, let's work from the terminal to connect to your `development` branch's database and make changes. 1. **Connect to your database** Get the connection string to your branch and connect to it directly via `psql`: neon connection-string development --database-name neondb --psql This command establishes the psql terminal connection to the `neondb` database on your development branch. 2. **Modify the schema** Add a new column `description` and index it: ALTER TABLE playing_with_neon ADD COLUMN description TEXT; CREATE INDEX idx_playing_with_neon_description ON playing_with_neon (description); 3. **Insert new data** Add new data that will be exclusive to the dev branch. INSERT INTO playing_with_neon (name, description) VALUES ('Your dev branch', 'Exploring schema changes in the dev branch'); 4. **Verify the schema changes** Query the table to verify your schema changes: SELECT * FROM playing_with_neon; Your response should include the new description column and a new row where name = `Your dev branch` and description = `Exploring schema changes in the dev branch`: id | name | value | description ----+--------------------+-------------+-------------------------------------------- 1 | c4ca4238a0 | 0.5315024 | 2 | c81e728d9d | 0.17189825 | 3 | eccbc87e4b | 0.21428405 | 4 | a87ff679a2 | 0.9721639 | 5 | e4da3b7fbb | 0.8649301 | 6 | 1679091c5a | 0.48413596 | 7 | 8f14e45fce | 0.82630277 | 8 | c9f0f895fb | 0.99945337 | 9 | 45c48cce2e | 0.054623786 | 10 | d3d9446802 | 0.36634886 | 11 | Your dev branch | | Exploring schema changes in the dev branch (11 rows) 8. [](#check-your-changes-with-schema-diff) Check your changes with Schema Diff ---------------------------------------------------------------------------- After making the schema changes to your development branch, you can use the [Schema Diff](/docs/guides/schema-diff) feature to compare your branch against its parent branch. Schema Diff is a GitHub-style code-comparison tool used to visualize differences between different branch's databases. For this tutorial, Schema Diff helps with validating isolation: it confirms that schema changes made in your isolated development branch remain separate from the production branch. From the **Branches** page in the Neon Console: 1. Open the detailed view for your `development` branch and click **Open schema diff**. 2. Verify the right branches are selected and click **Compare**. You can see the schema changes we added to our development branch highlighted in green. ![Schema diff from branches page](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fgetting_started_schema_diff.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) ### [](#schema-migrations) Schema Migrations A more typical scenario for Schema Diff is when preparing for schema migrations. While Neon does not provide built-in schema migration tools, you can use ORMs like [Drizzle](https://drizzle.team/) or [Prisma](https://www.prisma.io/) to handle schema migrations efficiently. Read more about using Neon in your development workflow in [Connect Neon to your stack](/docs/get-started-with-neon/connect-neon) . 9. [](#reset-your-development-branch-to-production) Reset your development branch to production -------------------------------------------------------------------------------------------- After experimenting with changes in your development branch, let's now reset the branch to `production`, its parent branch. [Branch reset](/docs/guides/reset-from-parent) functions much like a `git reset –hard parent` in traditional Git workflows. Resetting your development branches to your production branch ensures that all changes are discarded, and your branch reflects the latest stable state of `production`. This is key to maintaining a clean slate for new development tasks and is one of the core advantages of Neon's branching capabilities. You can reset to parent from the **Branches** page of the Neon Console, but here we'll use the Neon CLI. Use the following command to reset your `development` branch to the state of the `production` branch: Example: neon branches reset development --parent If you go back to your **Schema Diff** and compare branches again, you'll see they are now identical: ![schema diff after reset](/_next/image?url=%2Fdocs%2Fget-started-with-neon%2Fgetting_started_schema_diff_reset.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) ### [](#when-to-reset-your-branch) When to reset your branch Depending on your development workflow, you can use branch reset: * **After a feature is completed and merged** Once your changes are merged into `production`, reset the development branch to start on the next feature. * **When you need to abandon changes** If a project direction changes or if experimental changes are no longer needed, resetting the branch quickly reverts to a known good state. * **As part of your CI/CD automation** With the Neon CLI, you can include branch reset as an enforced part of your CI/CD automation, automatically resetting a branch when a feature is closed or started. Make sure that your development team is always working from the latest schema and data by including branch reset in your workflow. To read more about using branching in your workflows, see [Day 3 - Branching workfows](/docs/get-started-with-neon/workflow-primer) . #### working with sensitive data? Neon also supports schema-only branching. [Learn more](/docs/guides/branching-schema-only) . [](#need-help) Need help? ------------------------- Join our [Discord Server](https://discord.gg/92vNTzKDGp) to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more details, see [Getting Support](/docs/introduction/support) . [PreviousProduction readiness with Neon](/docs/get-started-with-neon/production-readiness) [Next2 - Connect Neon to your stack](/docs/get-started-with-neon/connect-neon) Last updated on April 17, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [About branching](#about-branching) * [1Sign up](#sign-up) * [2Onboarding in the Neon Console](#onboarding-in-the-neon-console) * [3Add sample data](#add-sample-data) * [4Try the AI Assistant](#try-the-ai-assistant) * [5View and modify data in the console](#view-and-modify-data-in-the-console) * [6Working with your development branch](#working-with-your-development-branch) * [7Make some sample schema changes](#make-some-sample-schema-changes) * [8Check your changes with Schema Diff](#check-your-changes-with-schema-diff) * [9Reset your development branch to production](#reset-your-development-branch-to-production) * [Need help?](#need-help) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/get-started-with-neon/signing-up.md) --- # Neon feature guides - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Features Neon feature guides =================== Explore Neon's capabilities with our feature guides [](#autoscaling) Autoscaling ---------------------------- Automatically scale compute resources up and down based on demand. * [### Learn about autoscaling\ \ Find out how autoscaling can reduce your costs.](/docs/introduction/autoscaling) * [### Enable autoscaling\ \ Enable autoscaling to automatically scale compute resources on demand](/docs/guides/autoscaling-guide) [](#scale-to-zero) Scale to zero -------------------------------- Enable or disable scale to zero for your Neon computes. * [### Learn about scale to zero\ \ Discover how Neon can reduce your compute to zero when not in use](/docs/introduction/scale-to-zero) * [### Configure scale to zero\ \ Enable or disable scale to zero to control if your compute suspends due to inactivity](/docs/guides/scale-to-zero-guide) [](#branching) Branching ------------------------ Branch data the same way you branch your code. * [### Learn about branching\ \ With Neon, you can instantly branch your data in the same way that you branch your code](/docs/introduction/branching) * [### Instant restore\ \ Restore your data to a past state with database branching](/docs/guides/branching-pitr) * [### Test queries on a branch\ \ Use branching to test queries before running them in production](/docs/guides/branching-test-queries) * [### Branching with the CLI\ \ Create and manage branches with the Neon CLI](/docs/guides/branching-neon-cli) * [### Branching with the API\ \ Create and manage branches with the Neon API](/docs/guides/branching-neon-api) * [### Branching with GitHub Actions\ \ Automate branching with GitHub Actions](/docs/guides/branching-github-actions) * [### Refresh a branch\ \ Refresh a development branch with the Neon API](/docs/guides/branch-refresh) [](#logical-replication) Logical replication -------------------------------------------- Replicate data from Neon to external data platforms and services. * [### Logical replication guide\ \ Get started with logical replication in Neon](/docs/guides/logical-replication-guide) * [### Logical replication concepts\ \ Learn about Postgres logical replication concepts](/docs/guides/logical-replication-concepts) * [### Logical replication commands\ \ Commands for managing your logical replication configuration](/docs/guides/logical-replication-manage) * [### Logical replication in Neon\ \ Information about logical replication specific to Neon](/docs/guides/logical-replication-neon) [](#read-replicas) Read replicas -------------------------------- Learn how Neon read replicas can help you scale and manage read-only workloads. * [### Learn about read replicas\ \ Learn how Neon maximizes scalability and more with read replicas](/docs/introduction/read-replicas) * [### Create and manage Read Replicas\ \ Learn how to create, connect to, configure, delete, and monitor read replicas](/docs/guides/read-replica-guide) * [### Scale your app with Read Replicas\ \ Scale your app with read replicas using built-in framework support](/docs/guides/read-replica-integrations) * [### Run analytics queries with Read Replicas\ \ Leverage read replicas for running data-intensive analytics queries](/docs/guides/read-replica-data-analysis) * [### Run ad-hoc queries with Read Replicas\ \ Leverage read replicas for running ad-hoc queries](/docs/guides/read-replica-adhoc-queries) * [### Provide read-only access with Read Replicas\ \ Leverage read replicas to provide read-only access to your data](/docs/guides/read-only-access-read-replicas) [](#time-travel) Time Travel ---------------------------- Travel back in time to view your database's history. * [### Learn about Time Travel\ \ Learn how to query point-in-time connections against your data's history](/docs/guides/time-travel-assist) * [### Time Travel tutorial\ \ Use Time Travel to analyze changes made to your database over time](/docs/guides/time-travel-tutorial) [](#schema-diff) Schema Diff ---------------------------- Compare your database branches. * [### Learn about Schema Diff\ \ Learn how to use Neon's Schema Diff tool to compare branches of your database](/docs/guides/schema-diff) * [### Schema Diff tutorial\ \ Step-by-step guide showing you how to compare two development branches using Schema Diff](/docs/guides/schema-diff-tutorial) [](#project-collaboration) Project collaboration ------------------------------------------------ Invite other users to collaborate on your Neon project. * [### Collaborate on your Neon project\ \ Give other users access to your project from the Neon Console, API, and CLI](/docs/guides/project-collaboration-guide) [](#ip-allow) IP Allow ---------------------- Limit access to trusted IP addresses. * [### Define your IP allowlist\ \ Learn how to limit database access to trusted IP addresses](/docs/introduction/ip-allow) [](#protected-branches) Protected branches ------------------------------------------ Protect your production or sensitive data. * [### Configure protected branches\ \ Learn how to use Neon's protected branches feature to secure access to critical data](/docs/guides/protected-branches) [](#private-networking) Private Networking ------------------------------------------ Secure your database connections with private access. * [### Private Networking\ \ Learn how to connect your application to a Neon database via AWS PrivateLink, bypassing the open internet](/docs/guides/neon-private-networking) [PreviousHigh availability](/docs/introduction/high-availability) [NextServerless](/docs/introduction/serverless) Last updated on January 10, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Autoscaling](#autoscaling) * [Scale to zero](#scale-to-zero) * [Branching](#branching) * [Logical replication](#logical-replication) * [Read replicas](#read-replicas) * [Time Travel](#time-travel) * [Schema Diff](#schema-diff) * [Project collaboration](#project-collaboration) * [IP Allow](#ip-allow) * [Protected branches](#protected-branches) * [Private Networking](#private-networking) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/guides/neon-features.md) --- # Neon use cases - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /Use cases Neon use cases ============== Explore popular Neon use cases * [### SaaS apps\ \ Build faster on Neon with autoscaling, database branching, and the serverless operating model](/docs/use-cases/saas-apps) * [### Variable traffic\ \ Optimize for performance without over-provisioning with Neon's Autoscaling feature](/docs/use-cases/variable-traffic) * [### Database-per-user\ \ Learn how you can build database-per-user architectures easily and cost-effectively](/docs/use-cases/database-per-user) * [### AI Agents\ \ Leverage Neon's instant Postgres database provisioning for AI agent development](/docs/use-cases/ai-agents) * [### Platforms\ \ Enable your users to create their own isolated Postgres databases](/docs/use-cases/platforms) * [### Dev/Test\ \ Boost developer productivity with Neon—a flexible development sandbox for running non-production workloads](/docs/use-cases/dev-test) [PreviousUpdates](/docs/manage/updates) [NextSaaS apps](/docs/use-cases/saas-apps) Last updated on February 11, 2025 Was this page helpful? YesNo Thank you for your feedback! [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/use-cases/use-cases-overview.md) --- # Neon for AI Agents - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /[Use cases](/docs/use-cases/use-cases-overview) /AI Agents Neon for AI Agents ================== Use Neon as the Postgres backend for your agents AI agents can now provision infrastructure, including databases. With AI agents already creating databases every few seconds, they are poised to manage a significant portion of the web's infrastructure in the future — and, like developers, AI agents love working with Neon: **Replit partnered with Neon to back Replit Agents, which are already creating thousands of Postgres databases per day**. [Learn more](https://neon.tech/blog/looking-at-how-replit-agent-handles-databases) . [](#what-makes-neon-a-good-database-for-ai-agents) What makes Neon a good database for AI Agents ------------------------------------------------------------------------------------------------ * **One-second provision times**. AI Agents generate code in seconds, so it's a bad user experience to wait minutes for a new Postgres instance to be deployed. Neon provisions databases nearly instantaneously, eliminating this friction. * **Scale to zero makes empty databases economically feasible**. Some databases created by agents might only be used for a few minutes; if you’re the company behind the agent, you’ll quickly have a large database fleet full of inactive databases. With Neon, that’s not a problem—you can still maintain this fleet within a reasonable budget. * **Straightforward API that even an AI Agent can use**. The same API endpoints that are useful for [developers managing large database fleets on Neon](/blog/how-retool-uses-retool-and-the-neon-api-to-manage-300k-postgres-databases) are also perfect for AI Agents. With the Neon API, you can not only create and delete databases but also track usage, limit resources, and handle configuration. * **Neon is 100% Postgres**. The most-loved database by developers worldwide is also the best choice for AI agents, thanks to its versatility (it works for almost any app) and the vast amount of resources, examples, and training datasets available. [](#tools-for-ai-agents) Tools for AI Agents -------------------------------------------- We recently published a package on NPM called [@neondatabase/toolkit](https://github.com/neondatabase/toolkit) , merging the already existing packages into a single SDK that is easier for AI agents to consume. [Read more](/blog/why-neondatabase-toolkit) . With a few lines of code, AI agents can use the **Neon toolkit** to create a Postgres database on Neon, run SQL queries, and tear down the database. Here's a quick look: import { NeonToolkit } from "@neondatabase/toolkit"; const toolkit = new NeonToolkit(process.env.NEON_API_KEY!); const project = await toolkit.createProject(); await toolkit.sql( project, ` CREATE TABLE IF NOT EXISTS users ( id UUID PRIMARY KEY, name VARCHAR(255) NOT NULL ); `, ); await toolkit.sql( project, `INSERT INTO users (id, name) VALUES (gen_random_uuid(), 'Sam Smith')`, ); console.log(await toolkit.sql(project, `SELECT name FROM users`)); await toolkit.deleteProject(project); Neon also supports a [Model Context Protocol (MCP) server](https://github.com/neondatabase/mcp-server-neon) that lets you use any MCP Client, such as Cursor or Claude Desktop, to manage Postgres databases with Neon using natural language; for example: * `Create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.` * `I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".` * `Can you give me a summary of all of my Neon projects and what data is in each one?` Both tools are open source. You can find them on GitHub. * [### @neondatabase/toolkit\ \ A terse client that lets you spin up a Postgres database in seconds and run SQL queries](https://github.com/neondatabase/toolkit) * [### Neon MCP Server\ \ A Model Context Protocol (MCP) server for Neon that lets MCP Clients interact with Neon’s API using natural language](/docs/ai/neon-mcp-server) [PreviousDatabase-per-user](/docs/use-cases/database-per-user) [NextPlatforms](/docs/use-cases/platforms) Last updated on March 7, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [What makes Neon a good database for AI Agents](#what-makes-neon-a-good-database-for-ai-agents) * [Tools for AI Agents](#tools-for-ai-agents) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/use-cases/ai-agents.md) --- # Database Branching Workflows - Neon [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Mastering Database Branching Workflows ====================================== Ship software faster using Neon branches as ephemeral environments [](#traditional-database-workflows-are-broken) Traditional database workflows are broken ---------------------------------------------------------------------------------------- Modern developer tooling keeps shortening the software lifecycle—but the database is still the bottleneck for many teams. Way too much engineering time is wasted in these tasks still today: * **Maintaining seed files.** Keeping seed data up to date across all environments is a pain that every production team has experienced. Any schema change or new production data requirement forces manual updates to seed files. This maintenance overhead increasingly grows, distracting engineers from the actual release. * **Manually setting up and resetting environments.** End-to-end testing requires clean, isolated environments. Traditional workflows—i.e. spinning up new database instances, manually importing seed data into all of them—create delays in the testing pipeline. * **Managing shared development instances.** Multiple developers share the same instance for dev cause concurrency issues. Productivity is slowed down due to conflicting changes or overwritten test data. The larger the team, the more of a time sink this is. To avoid this, some teams end up creating many, many dev databases. [](#how-neon-reimagines-them) How Neon reimagines them ------------------------------------------------------ To fix this broken system, we propose rethinking database workflows. Instead of using separate instances as independent development environments, we embrace the concept of **ephemeral environments**—environments that are by default short-lived, instantly deployable, active only when being used, and programmatically created or deleted. These ephemeral environments replicate an exact copy of both the schema and data from a parent environment. This allows teams to focus on maintaining a single parent environment while spinning up as many ephemeral environments as needed, without manual maintenance. How do you do it? With [Neon branches](https://neon.tech/docs/introduction/branching) . [](#turning-neon-branches-into-ephemeral-environments) Turning Neon branches into ephemeral environments -------------------------------------------------------------------------------------------------------- A Neon branch is a lightweight, copy-on-write clone of your database. It acts as an isolated, fully functional replica of the parent, including both schema and data, without requiring a full duplication of the underlying storage. Here’s how branches work: * **Copy-on-write.** When developers create a branch, Neon doesn’t duplicate the entire database. Instead, it references the same data pages as the parent environment. Only when a modification is made to the branch does Neon write a new copy of the changed data. * **Instant.** Because branches leverage the copy-on-write mechanism, they can be spun up in seconds, even for very large datasets. There’s no need to wait for lengthy data exports, imports, or replication setups. * **Ephemeral by design.** Neon branches are designed to be temporary. They can be created for a specific purpose—such as a development task, a test run, or staging for a deployment—and deleted once the task is complete. By default, the compute endpoint attached to them scales to zero. * **One-click reset.** Branches can be reset to match the parent environment instantaneously. With just a single click (or an API call), the branch discards all changes and reverts to the exact state of the parent. Having a clean slate for testing or development takes no effort. Only the parent needs to be maintained. > We’re a small team, but we’re scaling quickly and doing a lot. We’re shipping multiple times a day—to do that, we need to test stuff quickly and merge to main very quickly as well. Neon branches are a game changer for this. Avi Romanoff \- Founder at Magic Circle > Neon’s branching paradigm has been great for us. It lets us create isolated environments without having to move huge amounts of data around. This has lightened the load on our ops team, now it’s effortless to spin up entire environments. Jonathan Reyes \- Principal Engineer at Dispatch > Developers already face significant delays when working on a PR—running CI tests, ensuring everything is ready for preview, it all adds up. Time to launch is crucial for us: when we tried Neon and saw that spinning up a new branch takes seconds, we were blown away. Alex Co \- Head of Platform Engineering at Mindvalley [](#examples-of-database-branching-workflows-you-can-implement) Examples of database branching workflows you can implement -------------------------------------------------------------------------------------------------------------------------- The concept of database branching is new, and it takes a while to get used to. To help you visualize how it can be achieved in practice, we’ll cover three initial workflows: ### [](#preview-environment-workflow-one-database-branch-per-preview) Preview Environment Workflow: One Database Branch per Preview Each time a developer creates a pull request, Neon can generate a database branch that pairs with your preview deployment automatically, for example with Vercel previews. How it works: * The preview environment uses the preview branch, reflecting the same state as production at the moment the branch was created. * When the PR is closed, the branch is discarded. Why it’s better than the traditional workflow: * You get isolated and consistent testing environments for each pull request * Any schema changes in production can be reflected in a new preview without the need to manually updating any database * Bugs and errors are catched early because you’re testing on real data, not a mock ### [](#devtest-workflow-or-neon-twin) Dev/Test Workflow (or Neon Twin) In this workflow, you use Neon branches to create isolated environments for development and testing, mirroring a production-like state from a production database hosted outside of Neon (e.g., Amazon RDS). How it works: * Teams regularly sync a subset of production data or a testing dataset into a Neon main branch (e.g. via nightly dump/restores) * From this one branch, they create as many ephemeral environments as they need—e.g. to test features, run integration tests, or stage deployments * Once the task is completed, branches are discarded Why it’s better than the traditional workflow: * Hundreds of ephemeral environments can be created instantaneously, complete with schema and data * Everything can be automated via API, adding to existing CI/CD pipelines * If environments need to be reset, it takes one API call ### [](#local-development-workflow-one-database-branch-per-developer) Local Development Workflow: One Database Branch per Developer In this workflow, you use database branching to create personalized development environments for every developer on a team. How it works: * Each developer gets their own database branch, which is essentially a isolated copy of the main dataset Why it’s better than the traditional workflow: * Developers can work with realistic data sets instead of mocked or outdated seed files * Every developer has a fully independent environment, free from concurrency issues or conflicts, without needing to spin up a separate instance [](#preview-environment-workflow) Preview Environment Workflow -------------------------------------------------------------- To implement this workflow, follow the steps [in this guide.](https://neon.tech/docs/guides/vercel-previews-integration) The process looks like this: 1. Install the `Neon <> Vercel` integration * In the Neon Console, navigate to the Integrations section and select the Vercel integration * Click Add from Vercel to initiate the installation process * Follow the prompts to link your Neon account with your Vercel project 2. Configure the integration * During setup, choose the Neon project, database, and role that Vercel will use to connect * Enable the creation of a development branch for your Vercel development environment * Enable automatic deletion of Neon branches when the corresponding Git branches are merged or deleted 3. Deploy preview environments * With the integration configured, each time you push commits to a new branch in your source code repository, Vercel triggers a preview deployment * The integration automatically creates a corresponding database branch in Neon, named with the prefix `preview/` followed by your Git branch name * Vercel sets environment variables (`DATABASE_URL` and `DATABASE_URL_UNPOOLED`) to connect the preview deployment to the new Neon branch [](#devtest-workflow-neon-twin) Dev/Test Workflow (Neon Twin) ------------------------------------------------------------- [This guide](https://neon.tech/docs/use-cases/dev-test) will give you information on how to implement the Dev/Test workflow. The process changes slightly from team to team, but it looks like this: 1. Set up a Neon Project for your dev/test environments * Create a new project in the Neon Console, and name it appropriately (e.g., "Dev/Test Environments") 2. Create a Neon Twin * Establish a synchronized copy of your production or staging database (or a subset of it) within Neon’s main branch—which we call Neon Twin. This serves as the primary source for all your development and testing environments * Automate data synchronization using tools like `pg_dump/restore` or AWS DMS, scheduling regular updates (e.g., nightly) to keep the Neon Twin current. 3. Set up ephemeral environments as child branches * Create isolated child branches from the main branch for every individual development or testing tasks. This can be automated into your CI/CD pipelines via the Neon API. 4. Delete/reset branches * After completing development or testing, delete the child branches to conserve resources. This can be automatically set up. Environments can also be sync with the latest data and schema from the main branch instantaneously via an API call [](#local-development-workflow) Local Development Workflow ---------------------------------------------------------- To implement a local development workflow with a database branch per developer, follow these steps: 1. [Download the Neon CLI](/docs/reference/neon-cli#install) . 2. Connect your Neon account: neonctl auth 3. Create a database branch for each developer: neonctl branches create --name dev/developer_name 4. Get the connection string for the Neon database branch: neonctl connection-string dev/developer_name 5. Optionally, reset the development branch to the current state of `main` (data and schema). neonctl branches reset dev/developer_name --parent This step is useful when you want to discard the changes in your existing dev branch and start fresh with dev branch that reflects the current state of the parent's data and schema. [](#this-is-only-the-beginning) This is only the beginning ---------------------------------------------------------- The workflows described here are examples already popular among our users. We have ambitious plans to expand on them, such as incorporating anonymization of Personally Identifiable Information (PII). If you’d like to participate by providing feedback or testing a prototype, [reach out to us](https://neon.tech/contact-sales) . [See more branching workflows in the wild →](https://neon.tech/case-studies) Last updated on December 21, 2024 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Traditional database workflows are broken](#traditional-database-workflows-are-broken) * [How Neon reimagines them](#how-neon-reimagines-them) * [Turning Neon branches into ephemeral environments](#turning-neon-branches-into-ephemeral-environments) * [Examples of database branching workflows you can implement](#examples-of-database-branching-workflows-you-can-implement) * [Preview Environment Workflow](#preview-environment-workflow) * [Dev/Test Workflow (Neon Twin)](#devtest-workflow-neon-twin) * [Local Development Workflow](#local-development-workflow) * [This is only the beginning](#this-is-only-the-beginning) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/flow/index.md) --- # Import Data Assistant - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /[Migrate to Neon](/docs/import/migrate-intro) /Import Data Assistant Import Data Assistant ===================== Move your existing database to Neon using our guided tool When you're ready to move your data to Neon, our Import Data Assistant can help. You need only the connection string to your existing database to get started. #### Beta This feature is in Beta. Please give us [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://t.co/kORvEuCUpJ) . [](#how-it-works) How it works ------------------------------ Enter your current database connection string, and the Assistant will: 1. Run some preliminary checks on your database. If necessary, you'll be prompted to make changes to your source database before proceeding. Note that these are information checks only; the Assistant does not make any changes to your source database. 2. Based on these initial checks, the Assistant tries to create a Neon project that best matches your environment, such as region and Postgres version. 3. The Import Data Assistant provides `pg_dump` and `pg_restore` commands to transfer your data, pre-populated with the correct connection strings. Future versions will add more automation to these steps, and also add support for **logical replication** to help minimize downtime during larger transfers. 1. [](#before-you-start) Before you start -------------------------------------- You'll need the following to get started: * A **Neon account**. Sign up at [Neon](https://neon.tech) if you don't have one. * A **connection string** to your current database. Postgres connection strings use the format: `postgresql://username:password@host:port/database?sslmode=require&application_name=myapp` * **Admin privileges** or appropriate Postgres privileges on your source databases to perform the migration tasks. Using a superuser or a user with the necessary `CREATE`, `SELECT`, `INSERT`, and `REPLICATION` privileges is recommended. 2. [](#check-compatibility) Check compatibility -------------------------------------------- Enter the connection string from your source database. ![paste connection string for source db](/docs/import/migration_string.png) Neon will check the availability and configuration of your source database to help make sure your migration will be successful: * **Postgres version** — Verifies that your source database uses a version of Postgres that Neon supports (Postgres 14 to 17). * **Region** — Checks the hosting region of your source database. * **Supported Postgres extensions** — Identifies whether your extensions are supported by Neon. Unsupported extensions are listed, but you are not blocked from continuing the migration. Use your discretion. * **Compatible Postgres extension versions** — Checks that your extension versions match Neon's current support. See [Supported Postgres extensions](/docs/extensions/pg-extensions) for a matrix of extensions to Postgres versions in Neon. 3. [](#create-a-neon-project) Create a Neon project ------------------------------------------------ By default, we try to create your new project to match your source database: * Matching Postgres **version** * Matching **region** #### note This is an early feature and may not work for all regions or providers. You can modify any of these settings to suit the needs of your database, such as the host region, autoscaling range, and so on. See [Create a project](/docs/manage/projects#create-a-project) for more details about these options. ![create Neon project](/_next/image?url=%2Fdocs%2Fimport%2Fmigration_create_project.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) 4. [](#move-data-to-neon) Move data to Neon ---------------------------------------- Next, we'll send you to the command line. We generate the `pg_dump` and `pg_store` commands, pre-populated with the correct connection strings and required parameters. ![move data to Neon using pg_dump and pg_restore](/docs/import/migration_move_data.png) The `pg_dump` command is populated with your source database: pg_dump -Fc -v -d "postgresql://:@:/" -f database.bak The `pg_restore` command uses the connection string for the database in your newly created project in Neon: pg_restore -v -d "postgresql://:@:/" database.bak For more detailed instructions about using these commands, see [Migrate data using pg\_dump and pg\_restore](/docs/import/migrate-from-postgres) . 5. [](#next-steps) Next Steps -------------------------- 1. **Verify data integrity** by running some queries and checking that tables and data are present as expected in Neon. 2. **Switch over your application** by updating your connection string to point to Neon. You can find your connection details on your project Dashboard. See [Connect from any application](/docs/connect/connect-from-any-app) for more information. [](#it-didnt-work-what-can-i-do) It didn't work. What can I do? --------------------------------------------------------------- If your database migration failed because of an incompatibility, a connection issue, or another problem, contact us for [migration assistance](https://neon.tech/migration-assistance) . We're here to help you get up and running. [PreviousMigrate to Neon](/docs/import/migrate-intro) [NextMigrate from Postgres with pg\_dump and pg\_restore](/docs/import/migrate-from-postgres) Last updated on March 6, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [How it works](#how-it-works) * [1Before you start](#before-you-start) * [2Check compatibility](#check-compatibility) * [3Create a Neon project](#create-a-neon-project) * [4Move data to Neon](#move-data-to-neon) * [5Next Steps](#next-steps) * [It didn't work. What can I do?](#it-didnt-work-what-can-i-do) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/import/import-data-assistant.md) --- # Neon for Development and Testing - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /[Use cases](/docs/use-cases/use-cases-overview) /Dev/Test Neon for Development and Testing ================================ Boost developer productivity with Neon—a flexible development sandbox for running non-production workloads. What sets Neon apart from other Postgres providers, beyond its true serverless nature, is its focus on delivering an exceptional developer experience. Here are some of our standout features: [](#standout-features) Standout features ---------------------------------------- Together, these features create a fast, flexible, and developer-friendly database experience that traditional solutions can’t match. 1. **Serverless Architecture with Autoscaling**: Neon automatically scales resources to match workload demand, with no manual intervention required. 2. **Branching for Development and Testing**: Neon enables instant branching that creates isolated copies of data and schema. This allows for safe development and testing without impacting production. 3. **Integration and Compatibility**: Neon supports all the latest PostgreSQL versions and numerous extensions, ensuring compatibility with a wide range of applications and frameworks. 4. **Provisioning Environments**: Neon simplifies the provisioning and management of environments through its console or API. New databases and branches can be spun up instantly, resources can be managed, and settings configured—either through a user-friendly console or automated API calls. [](#move-non-production-to-neon) Move non-production to Neon ------------------------------------------------------------ Not every team is ready for a full database migration. However, even if teams aren’t ready to migrate their production databases, they can still improve efficiency by moving their non-production workloads to Neon using a [Neon Twin](/docs/guides/neon-twin-intro) . ![Dev/Test Twin Workflow](/_next/image?url=%2Fuse-cases%2Fdev-test-twin-workflow.png&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Create a Neon Twin ------------------ A Neon Twin is a full or partial clone of your production or staging database, providing developers and teams with isolated, sandboxed environments that closely mirror production. Learn how to create a Twin [here](/docs/guides/neon-twin-intro) . [](#workflows) Workflows ------------------------ Most teams running dev/test workloads on Neon while keeping production on another Postgres platform implement a workflow similar to this: 1. **Set up a Neon Project for dev/test environments** Teams start by [creating a single Neon project](/docs/get-started-with-neon/signing-up#sign-up) to host multiple dev/test environments. 2. **Create a Neon Twin** Next, teams create a [Neon Twin](/docs/guides/neon-twin-intro) —a full or partial clone of their production or staging database that remains automatically synchronized. 3. **Develop on branches** Once a Neon Twin is set up, teams can instantly create [branches](/docs/introduction/branching) . These branches are fully isolated and provide teams with a complete copy of the testing dataset immediately. 4. **Migrate changes** Migrate changes developed and tested on a Twin back to your production or staging database using your existing workflows. [](#further-reading) Further Reading ------------------------------------ * [Neon Twin: Move Dev/Test/Staging to Neon, Keep Production on RDS](https://neon.tech/blog/optimizing-dev-environments-in-aws-rds-with-neon-postgres-part-ii-using-github-actions-to-mirror-rds-in-neon) * [Building Slack notifications to monitor pg\_dump and restore workflows](https://neon.tech/blog/building-slack-notifications-to-monitor-pg_dump-and-restore-workflows) * [Neon Twin: How to deploy a change tested in Neon to prod in RDS](https://neon.tech/blog/neon-twin-deploy-workflow) Let's Connect ------------- We’re happy to give you a hand with any technical questions about how to set this workflow up. We can also discuss pricing options, annual contracts, and provide migration assistance. [Contact us](/contact-sales) [PreviousPlatforms](/docs/use-cases/platforms) [NextRegions](/docs/introduction/regions) Last updated on February 20, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Standout features](#standout-features) * [Move non-production to Neon](#move-non-production-to-neon) * [Workflows](#workflows) * [Further Reading](#further-reading) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/use-cases/dev-test.md) --- # Neon for SaaS apps - Neon Docs [We compiled tips and tricks for writing great code with LLMs. Make the most of tools like Cursor, Claude, Devin![](/_next/static/svgs/9ee958f8b2be7694e4ce9140c14df68e.svg)](https://neon.tech/blog/treat-ai-like-a-senior-dev-not-a-junior-one) Search [Neon Docs](/docs/introduction) [Ask Neon AI](/ai-chat) [Docs](/docs) /[Use cases](/docs/use-cases/use-cases-overview) /SaaS apps Neon for SaaS apps ================== Build SaaS apps faster on Neon with autoscaling, database branching, and the serverless operating model Teams are accelerating development workflows and reducing operational overhead with Neon’s database branching, autoscaling, and serverless operating model. Learn how you can do the same. [](#summary) Summary -------------------- There are three key features that are helping teams develop SaaS applications faster and more efficiently with Postgres on Neon: ✓Database Branching[](#database-branching) Create isolated environments with production-like copies of your data and schema for testing, development, and CI/CD workflows. ✓Autoscaling[](#autoscaling) CPU, memory, and storage automatically scale up or down to match your workload. Avoid paying for unused resources. ✓Neon's Serverless Operating Model[](#neon's-serverless-operating-model) Skip managing `pg_hba.conf` files or SSH access. Neon simplifies operational tasks with an intuitive UI and API. [](#key-features) Key features ------------------------------ * * * ### [](#database-branching) Database branching ![Database Branching](/_next/image?url=%2Fdocs%2Fuse-cases%2Fbranching.jpg&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) A branch in Neon is a copy-on-write clone of your database, including both schema and data. Branches function like Git branches, enabling development, testing, and preview environments. * **Instant branch creation**: Independent of database size, with no duplicated storage. * **Cost-efficient branches**: One customer with a team of five developers handles all dev, test, and preview work through branches, spending ~$150/month. * **Idle branch computes scale to zero**: Further reducing costs. How branches boost development velocity: ✓Onboard faster and keep in sync[](#onboard-faster-and-keep-in-sync) You can give each developer their own branch for local development. Developers can use [branch reset](docs/introduction/branching#restore-and-recover-data) to instantly restore and sync with the latest changes. ✓Accelerate feature development and code reviews[](#accelerate-feature-development-and-code-reviews) Automate branch creation for each Git branch or pull request. Use tools like GitHub Actions or Neon's integrations: \- [Neon GitHub Integration](/docs/guides/neon-github-integration) : Easily create a branch for every PR. \- [Neon Vercel Integration](/docs/guides/vercel) : Create and integrate a branch into every Vercel preview deployment. ✓Enhance testing and CI/CD[](#enhance-testing-and-cicd) Run test suites on exact copies of your production database using branches. Save time with instant branch creation, shaving minutes off every test run. * * * ### [](#autoscaling) Autoscaling ![Neon Autoscaling](/_next/image?url=%2Fdocs%2Fuse-cases%2Fautoscaling.jpg&w=1920&q=75&dpl=dpl_BBbAMJDhTebRNZQCGXiX2Dabk5Tc) Neon's autoscaling dynamically adjusts compute resources based on current load, removing the need for manual intervention. For teams building SaaS on Neon, autoscaling offers several benefits: ✓Performance and cost-efficiency[](#performance-and-cost-efficiency) Get performance without over-provisioning. On average, [60% of database costs come from unused resources.](https://medium.com/@carlotasotos/database-economics-an-amazon-rds-reflection-5d7a35638b20) ✓No manual resizing[](#no-manual-resizing) Unlike other platforms that limit resizing, require downtime, or only allow scaling up, Neon automates scaling both up and down instantly. ✓Minimized outage risk[](#minimized-outage-risk) Setting a high autoscaling limit helps prevent database downtime during unexpected traffic surges. * * * ### [](#serverless-operating-model) Serverless operating model Neon abstracts away the concept of servers so that customers can focus on building their SaaS application, not managing their database: * **No server management**: You don’t need to provision, maintain, administer servers. * **Managed infrastructure**: Neon handles all underlying infrastructure, including security patches, load balancing, and capacity planning. * **Built-in availability and fault tolerance**: Neon is designed to minimize customer-facing impact in event of hardware failure. * **Focus on business logic**: You can concentrate on writing code for your application's core functionality rather than dealing with infrastructure concerns. * * * [](#database-per-user-architectures) Database-per-user architectures -------------------------------------------------------------------- If your SaaS project could benefit from multitenancy, Neon makes it simple to create a dedicated database for each user: * **No pre-provisioning**: In Neon, there’s no need to provision infrastructure in advance. You can scale your architecture progressively, from a few tenants to thousands, without breaking the bank. * **Cost efficiency**: You only pay for the Neon instances that are actively running. Thanks to scale-to-zero, creating instances doesn’t incur compute costs unless they’re actually in use. * **Instant deployment**: Neon databases are created in milliseconds via APIs. An API call can spin up a new project whenever your end-user needs a database, without slowing things down. [More info on Database per Tenant](/docs/use-cases/database-per-user) [](#table-stakes) Table stakes ------------------------------ Differentiated features are great, but what about the basics... Does Neon meet the requirements for your use case? ### [](#compatibility) Compatibility * * * ✓It's Just Postgres[](#it's-just-postgres) Deploy Postgres 14, 15, 16, and 17 on Neon. There is no lock-in, no proprietary syntax to learn. ✓Integrates with any language/framework[](#integrates-with-any-languageframework) Anything that has a Postgres driver or integration works with Neon. ✓70+ Postgres extensions[](#70+-postgres-extensions) `pgvector`, `postGIS`, `timescaledb` and [many other popular Postgres extensions](/docs/extensions/pg-extensions) are supported on Neon ✓Logical Replication[](#logical-replication) Inbound (Neon as subscriber) and outbound (Neon as publisher) logical replication are supported. ✓Serverless (HTTP) Driver[](#serverless-(http)-driver) Unlock access from serverless environments like AWS Lambda and Cloudflare Workers with the [Neon serverless driver](/docs/serverless/serverless-driver) . It uses an HTTP API to query from edge/serverless with lower latency. ### [](#performance-and-scale) Performance and scale * * * * **Similar Latency Characteristics to RDS Postgres** Prisma recently published [performance benchmarks](https://benchmarks.prisma.io/?dbprovider=pg-rds) showing similar latency between AWS RDS and Neon. * **Self-Serve Autoscaling from zero to 16 CU** Configure Neon to autoscale up to 16 CPU, 64 GB RAM. [Contact our team](/contact-sales) to unlock larger computes. * **Storage up to 2TB** Storage scales seamlessly based on usage. [Contact our team](/contact-sales) for custom rates on 2tb+ storage. * **Instant Read Replicas** Read replicas on Neon are faster to create, and only add compute (not storage) making them a cost efficient means of separating workloads. ### [](#security-and-compliance) Security and compliance * * * —IP Allow List[](#ip-allow-list) Scale and Business Plan accounts can lock down database access to specific IP addresses or ranges. —SOC 2 Type 2 Compliant[](#soc-2-type-2-compliant) Neon has been SOC 2 Type 2 Compliant since Dec 2, 2023. View full compliance details in the [Trust Center](https://trust.neon.tech/) . —HIPAA Compliant[](#hipaa-compliant) Neon is HIPAA compliant. For more information about our compliance certifications, visit our [Trust Center](https://trust.neon.tech/) . ### [](#cost) Cost * * * ✓Usage-Based Billing[](#usage-based-billing) Paid plans start at $19 for an allotment of Compute and Storage resources, and scale up predictably as your workload grows. ✓Pay via AWS Marketplace[](#pay-via-aws-marketplace) If your business is already active on AWS, you may be able to save hassle and budgets by [paying for Neon via AWS Marketplace](https://neon.tech/docs/introduction/billing-aws-marketplace) . ✓Pay via Azure Marketplace[](#pay-via-azure-marketplace) If your business runs on Azure, Neon is available as a [native Azure integration](/docs/introduction/billing-azure-marketplace) , with billing through Azure. Have any questions or need more information? -------------------------------------------- Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started. [Reach out to us](/contact-sales) [PreviousUse cases](/docs/use-cases/use-cases-overview) [NextVariable traffic](/docs/use-cases/variable-traffic) Last updated on March 10, 2025 Was this page helpful? YesNo Thank you for your feedback! ### On this page * [Summary](#summary) * [Key features](#key-features) * [Database-per-user architectures](#database-per-user-architectures) * [Table stakes](#table-stakes) [Edit this page on GitHub](https://github.com/neondatabase/website/tree/main/content/docs/use-cases/saas-apps.md) ---