DOCSEARCHbyAlgolia
Submit Docs

Neon Website and Documentation Framework

repository·main·Indexed 43 days ago

https://github.com/neondatabase/website

Developer guide for the Neon Next.js website, covering documentation site configuration, markdown frontmatter, navigation management via navigation.yaml, and a comprehensive library of MDX components including CodeTabs, ExternalCode, InlineSvg, Admonitions, TwoColumnLayout, and Faq.

Tokens
362.2K
Snippets
1.1K
Records
1.6K
Agent score
55%

What's inside Neon

  1. Overview of Neon's icon systems

    main

    Neon uses different icon systems depending on the component being used. When designing or contributing components, identify which system is required to ensure visual consistency:

    • TechCards: Uses colorful technology logos located in /public/images/technology-logos/.
    • DetailIconCards: Uses monochrome feature icons that are mapped directly within the component code.
    • DocsList: Uses built-in themes designed for simple navigation.

    Always verify icon compatibility by testing them within the specific target component before final implementation.

  2. Overview of Neon OpenTelemetry integration

    main

    The Neon OpenTelemetry integration allows Scale plan users to export Postgres metrics and logs to any OTLP-compatible observability platform (e.g., Grafana Cloud, New Relic, Honeycomb).

    Neon automatically collects data from all computes in your project, including multiple branches. The integration uses the OpenTelemetry Protocol (OTLP) via HTTP or gRPC to transmit data.

    Exported Data Types:

    • Metrics: Includes connection counts, database size, replication delay, and compute metrics (CPU/memory usage).
    • Postgres logs: Includes error messages, warnings, connection events, and system notifications.

  3. Overview of Neon Object Storage

    main

    Neon Object Storage is an S3-compatible file storage system integrated into your Neon project. A key feature is that it branches with your database: when you create a database branch, the object storage also branches, providing an isolated namespace for that branch. This allows you to test file operations (uploads/deletions) in preview branches without affecting production data.

    Key Features

    • S3 Compatibility: Works with any standard S3 SDK (AWS SDK for JavaScript, boto3, AWS CLI) or tools like the Files SDK.
    • Access Modes:
      • private: Requires authentication for all operations.
      • public_read: Allows anonymous reads, but requires authentication for writes.
    • Unified Credentials: Uses the same Neon credential system used by AI Gateway and Functions.

    Regional Availability

    Currently available in:

    • AWS US East (Ohio) (aws-us-east-2)
    • AWS Europe (Frankfurt) (aws-eu-central-1)

  4. Capabilities of Neon Agent Skills

    main

    When the full skill set is installed, an AI assistant can assist with several categories of Neon platform tasks:

    Postgres and Platform Basics

    • Getting started: Project setup and core features like branching, autoscaling, scale-to-zero, instant restore, and read replicas.
    • Connections: Guidance on the serverless driver, connection pooling, and connection strings.
    • Authentication: Setting up Managed Better Auth.
    • Data API: Using @neondatabase/neon-js.
    • Platform APIs and SDKs: Using the REST API, TypeScript SDK, and Python SDK.
    • Developer tools: Using the CLI, VS Code extension, and MCP server.

    Database Workflows

    • Disposable projects: Using Claimable Neon for agents and tests.
    • Branching: Workflows for migrations, schema-only branches, and reset-from-parent.
    • Egress optimization: Identifying high transfer costs and query anti-patterns.

    Platform Services

    • Neon Functions: Declaring, deploying, and connecting long-running compute next to your database.
    • Object Storage: Using S3-compatible storage that branches with your data.
    • AI Gateway: Model routing, logging, and cost controls using a single Neon credential.

  5. Use the Neon CLI `branches` command

    main

    The branches command allows you to manage Neon project branches from your terminal. You can list, create, rename, delete, and retrieve branch details, as well as set default branches, add compute/read replicas, perform point-in-time restores, and run schema diffs.

    If you omit the --project-id flag, the CLI will attempt to resolve it from your local context file, auto-select it if your account has only one project, or prompt you if multiple projects exist.

    To pin a specific branch in your local .neon context file so that subsequent commands target it automatically, use the neon checkout command.

    neon branches [subcommand] [flags]

  6. Explore Neon's backend primitives for apps and agents

    main

    Neon is expanding beyond core Postgres to provide a branchable stack of backend primitives. Key upcoming and current primitives include:

    • Managed Better Auth: Moving toward general availability with upcoming plugins and features. See the Managed Better Auth roadmap for specific details.
    • Functions: Node.js functions that are deployed alongside your database.
    • Object Storage: S3-compatible object storage that supports branching alongside your database projects.
    • AI Gateway: A unified API for accessing frontier and open-source models, powered by Databricks.

  7. Compare Prisma, Drizzle, and TypeORM for Postgres

    main

    When choosing a data layer for a TypeScript or JavaScript service on Postgres, you can choose between three primary approaches. Note that Neon is the database platform and is independent of your ORM choice; you connect to Neon using a standard connection string and driver.

    Comparison Summary

    FeaturePrismaDrizzleTypeORM
    Core PhilosophySchema-first (Declarative DSL)TypeScript-first (SQL-shaped)Class-first (Decorator-based)
    Schema Definition.prisma fileTypeScript codeTypeScript classes with decorators
    Query StyleHigh-level generated clientSQL-like APIRepository or QueryBuilder
    Migration ToolingPrisma MigrateDrizzle KitCLI-based entity diffs
    Best ForRapid CRUD & relationship managementServerless, Edge, & SQL-heavy teamsExisting class-based/Entity Framework-style apps

  8. Understand Neon's core Postgres roadmap

    main

    Neon is actively developing several core database capabilities:

    Real-time sync

    Real-time Postgres sync powered by the Electric sync engine. This allows keeping databases and connected clients (browser tabs, mobile apps, and agents) in continuous sync for collaborative and agentic applications.

    Backups & restore

    Planned features include:

    • Externally exported backups
    • Integration with external backup systems
    • Cross-region and cross-cloud branch snapshots and exported backups

    Security

    Planned security enhancements include:

    • Custom key support for encryption at rest
    • Customer-managed key (CMK) support for application-level encryption
    • Kerberos and LDAP authentication support
    • Mutual TLS (mTLS) connections

    Postgres compute

    • Postgres 19 support: Currently supports Postgres 14 through 18.
    • Performance: Optimizations for startup performance on larger compute instances.
    • Scaling: Fixed compute sizes up to 128 CUs and autoscaling up to 60 CUs.

    Account security & Compliance

    • RBAC: Role-based access control in the Neon Console and extended into the database.
    • Audit logging: Logging of all database access.
    • Compliance: PCI compliance is on the roadmap.

  9. PostgreSQL 18 New Features Overview

    main

    PostgreSQL 18 introduces several major updates designed to modernize the database for cloud-native workloads while maintaining backward compatibility. Key improvements include:

    Performance Improvements

    • Asynchronous I/O: A significant architectural update for I/O operations.
    • B-tree Skip Scan Support: Enhances query performance for certain index scans.
    • Query Optimization Enhancements: General improvements to the query planner and execution.

    Developer Experience Improvements

    • Virtual Generated Columns: A new way to define columns (set to Default behavior).
    • UUIDv7 Support: Native support for timestamp-ordered UUIDs.
    • Enhanced RETURNING Clause: Expanded capabilities for the RETURNING clause in SQL statements.
    • Temporal Constraints WITHOUT OVERLAPS: Improved handling of temporal data constraints.

    Security Features

    • OAuth Authentication: Support for OAuth-based authentication flows.

    Note: Neon will transition these features from preview to full support once current limitations are addressed.

  10. Understand the project structure

    main

    The repository follows a standard Next.js structure with specific organization for components and content:

    • content/: Documentation sources in mdbook format.
    • public/: Static assets.
    • src/app/: Next.js App Router pages.
    • src/components/pages/: React components used specifically on a certain page.
    • src/components/shared/: React components used across the entire website.
    • src/hooks/, src/icons/, src/images/, src/lib/, src/scripts/, src/styles/, src/utils/: Supporting directories.
    • next.config.js: Main Next.js configuration.
    • postcss.config.js: PostCSS configuration.
    • tailwind.config.js: Tailwind CSS configuration.

  11. Match Neon features to your growth stage

    main

    Neon's architecture is designed to scale across three primary growth stages without requiring a change in database architecture:

    1. Side Projects: Focuses on simplicity and zero cost. Features include a Free plan (up to 100 projects, 2 CUs, and 0.5 GB storage per project), scale-to-zero compute to save limits, and standard Postgres compatibility.
    2. Startups: Focuses on rapid iteration. Key features include Autoscaling for unpredictable workloads, Branching for instant dev/preview environments, Connection Pooling for serverless apps, and API-first workflows for automation.
    3. Scale-ups and Large Fleets: Focuses on operational efficiency and multi-tenancy. Key features include On-demand storage, High Availability via storage redundancy, Snapshot-based backup/restore, and Database-per-tenant isolation.

  12. Compose backends using Neon primitives

    main

    Neon provides a modular set of cloud backend primitives built around Lakebase Postgres. You can adopt only the pieces you need:

    • Lakebase Postgres: The core database engine.
    • Managed Better Auth: Authentication and identity within Postgres.
    • Object Storage: S3-compatible files and blobs.
    • Functions: Long-running compute located next to your data.
    • Data API: HTTP access to your database.
    • AI Gateway: Unified model access with a single credential.