refactor: reorder analytics columns for readability, fix neon update error handling

Put timestamp/type/host/path first, move event_id and metadata last.
ClickHouse ORDER BY now includes timestamp for efficient time-range queries.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vklimontovich

packages/core/src/backends/lib/db.ts

@@ -1,21 +1,21 @@
 import type { ClientContext, NextlyticsEvent, ServerEventContext } from "../../types";
 
 export const tableColumns = [
-  { name: "event_id", pgType: "TEXT PRIMARY KEY", chType: "String" },
-  { name: "parent_event_id", pgType: "TEXT", chType: "Nullable(String)" },
-  { name: "timestamp", pgType: "TIMESTAMPTZ", chType: "DateTime64(3)" },
-  { name: "type", pgType: "TEXT", chType: "LowCardinality(String)" },
-  { name: "anonymous_user_id", pgType: "TEXT", chType: "Nullable(String)" },
+  { name: "timestamp", pgType: "TIMESTAMPTZ NOT NULL", chType: "DateTime64(3)" },
+  { name: "type", pgType: "TEXT NOT NULL", chType: "LowCardinality(String)" },
+  { name: "host", pgType: "TEXT", chType: "LowCardinality(String)" },
+  { name: "path", pgType: "TEXT", chType: "String" },
+  { name: "method", pgType: "TEXT", chType: "LowCardinality(String)" },
   { name: "user_id", pgType: "TEXT", chType: "Nullable(String)" },
+  { name: "anonymous_user_id", pgType: "TEXT", chType: "Nullable(String)" },
   { name: "user_email", pgType: "TEXT", chType: "Nullable(String)" },
   { name: "user_name", pgType: "TEXT", chType: "Nullable(String)" },
-  { name: "host", pgType: "TEXT", chType: "LowCardinality(String)" },
-  { name: "method", pgType: "TEXT", chType: "LowCardinality(String)" },
-  { name: "path", pgType: "TEXT", chType: "String" },
   { name: "ip", pgType: "INET", chType: "Nullable(IPv6)" },
   { name: "referer", pgType: "TEXT", chType: "Nullable(String)" },
   { name: "user_agent", pgType: "TEXT", chType: "Nullable(String)" },
   { name: "locale", pgType: "TEXT", chType: "LowCardinality(Nullable(String))" },
+  { name: "event_id", pgType: "TEXT PRIMARY KEY", chType: "String" },
+  { name: "parent_event_id", pgType: "TEXT", chType: "Nullable(String)" },
   { name: "server_context", pgType: "JSONB", chType: "JSON" },
   { name: "client_context", pgType: "JSONB", chType: "JSON" },
   { name: "user_traits", pgType: "JSONB", chType: "JSON" },
@@ -70,21 +70,21 @@ function extractCommonFields(event: NextlyticsEvent) {
     : null;
 
   return {
-    event_id: event.eventId,
-    parent_event_id: event.parentEventId ?? null,
     timestamp: event.collectedAt,
     type: event.type,
-    anonymous_user_id: event.anonymousUserId ?? null,
+    host,
+    path,
+    method,
     user_id: event.userContext?.userId ?? null,
+    anonymous_user_id: event.anonymousUserId ?? null,
     user_email: event.userContext?.traits?.email ?? null,
     user_name: event.userContext?.traits?.name ?? null,
-    host,
-    method,
-    path,
     ip: ip || null,
     referer: clientCtx.referer ?? null,
     user_agent: clientCtx.user_agent ?? null,
     locale: clientCtx.locale ?? null,
+    event_id: event.eventId,
+    parent_event_id: event.parentEventId ?? null,
     serverContextRest,
     clientContextRest: clientCtx.rest,
     userTraitsRest,
@@ -119,9 +119,9 @@ export function eventToJsonRow(event: NextlyticsEvent): Record<ColumnName, unkno
 
 // Postgres
 export function generatePgCreateTableSQL(tableName: string): string {
-  const pk = tableColumns[0];
+  const pk = tableColumns.find((c) => c.pgType.includes("PRIMARY KEY"))!;
   const alters = tableColumns
-    .slice(1)
+    .filter((c) => c !== pk)
     .map((col) => `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS ${col.name} ${col.pgType};`)
     .join("\n");
 
@@ -142,7 +142,7 @@ export function generateChCreateTableSQL(database: string, tableName: string): s
     .join(", ");
   const create =
     `CREATE TABLE IF NOT EXISTS ${fullTable} (${createCols}) ` +
-    `ENGINE = ReplacingMergeTree() PARTITION BY toYYYYMM(timestamp) ORDER BY event_id;`;
+    `ENGINE = ReplacingMergeTree() PARTITION BY toYYYYMM(timestamp) ORDER BY (timestamp, event_id);`;
 
   const alters = tableColumns
     .filter((c) => c.name !== "event_id" && c.name !== "timestamp")
@@ -158,21 +158,21 @@ export function isChTableNotFoundError(text: string): boolean {
 
 /** Row type returned from analytics table queries */
 export interface AnalyticsEventRow {
-  event_id: string;
-  parent_event_id: string | null;
   timestamp: string;
   type: string;
-  anonymous_user_id: string | null;
+  host: string;
+  path: string;
+  method: string;
   user_id: string | null;
+  anonymous_user_id: string | null;
   user_email: string | null;
   user_name: string | null;
-  host: string;
-  method: string;
-  path: string;
   ip: string | null;
   referer: string | null;
   user_agent: string | null;
   locale: string | null;
+  event_id: string;
+  parent_event_id: string | null;
   server_context: Record<string, unknown>;
   client_context: Record<string, unknown>;
   user_traits: Record<string, unknown>;

packages/core/src/backends/neon.ts

@@ -70,10 +70,17 @@ export function neonBackend(config: NeonBackendConfig): NextlyticsBackend {
 
       if (sets.length > 0) {
         params.push(eventId);
-        await sql.query(
-          `UPDATE ${table} SET ${sets.join(", ")} WHERE event_id = $${paramIndex}`,
-          params
-        );
+        try {
+          await sql.query(
+            `UPDATE ${table} SET ${sets.join(", ")} WHERE event_id = $${paramIndex}`,
+            params
+          );
+        } catch (err) {
+          if (isPgTableNotFoundError(err)) {
+            printCreateTableStatement();
+          }
+          throw err;
+        }
       }
     },
   };

packages/website/src/copy/integrations/neon/documentation.mdx

@@ -25,34 +25,70 @@ database. It's optimized for serverless environments with connection pooling.
 
 ## Table Schema
 
-On first use, if the table doesn't exist, Nextlytics will print the required CREATE TABLE statement.
-Run it in your Neon SQL editor:
+On first use, if the table doesn't exist, Nextlytics will print the required
+CREATE TABLE statement. Run it in your Neon SQL editor:
 
 ```sql
 CREATE TABLE IF NOT EXISTS analytics (
-  event_id TEXT PRIMARY KEY,
+  timestamp TIMESTAMPTZ NOT NULL,
   type TEXT NOT NULL,
-  collected_at TIMESTAMPTZ NOT NULL,
-  anonymous_user_id TEXT,
-  user_id TEXT,
-  path TEXT,
   host TEXT,
+  path TEXT,
   method TEXT,
-  ip TEXT,
+  user_id TEXT,
+  anonymous_user_id TEXT,
+  user_email TEXT,
+  user_name TEXT,
+  ip INET,
   referer TEXT,
   user_agent TEXT,
   locale TEXT,
-  properties JSONB,
+  event_id TEXT PRIMARY KEY,
+  parent_event_id TEXT,
   server_context JSONB,
   client_context JSONB,
-  user_context JSONB
+  user_traits JSONB,
+  properties JSONB
 );
 
-CREATE INDEX idx_analytics_collected_at ON analytics(collected_at DESC);
+CREATE INDEX idx_analytics_timestamp ON analytics(timestamp DESC);
 CREATE INDEX idx_analytics_type ON analytics(type);
 CREATE INDEX idx_analytics_user_id ON analytics(user_id);
 ```
 
+If you're using Prisma, add this model to your `schema.prisma` instead:
+
+```prisma
+model Analytics {
+  timestamp        DateTime @db.Timestamptz()
+  type             String
+  host             String
+  path             String
+  method           String
+  user_id          String?
+  anonymous_user_id String?
+  user_email       String?
+  user_name        String?
+  ip               String?  @db.Inet
+  referer          String?
+  user_agent       String?
+  locale           String?
+  event_id         String   @id
+  parent_event_id  String?
+  server_context   Json?    @db.JsonB
+  client_context   Json?    @db.JsonB
+  user_traits      Json?    @db.JsonB
+  properties       Json?    @db.JsonB
+
+  @@index([timestamp(sort: Desc)])
+  @@index([type])
+  @@index([user_id])
+  @@map("analytics")
+}
+```
+
+Then run `npx prisma db push` or add a migration with `npx prisma migrate dev`.
+
 ## Event Updates
 
 Neon backend supports event updates. When client context becomes available (after the initial
@@ -85,10 +121,10 @@ FROM analytics
 WHERE type = 'purchase';
 
 -- User journey
-SELECT type, path, collected_at
+SELECT type, path, timestamp
 FROM analytics
 WHERE user_id = 'user_123'
-ORDER BY collected_at;
+ORDER BY timestamp;
 ```
 
 ## Branching