How to Integrate Bolt.new with Oracle Database

The oracledb npm package has a hard requirement on Oracle Instant Client — a set of native shared libraries that must be present on the operating system running Node.js. When you add oracledb to a Bolt project, the npm install succeeds, but the module cannot load because there is no way to install Oracle Instant Client in the WebContainer's virtual filesystem. The error at runtime is: 'Error: DPI-1047: 64-bit Oracle Client library cannot be loaded. See https://oracle.github.io/odpi/doc/installation.html'. Even if Instant Client could be installed somehow, there is a second constraint: WebContainers block raw TCP connections, and Oracle Net (the protocol oracledb uses to talk to Oracle Database) requires TCP connectivity to port 1521 (or your configured Oracle listener port). This is the same TCP blocking that affects MongoDB's native driver. This means: code using oracledb, db.execute(), or oracle connection strings will never work in the Bolt WebContainer preview. The code is syntactically correct and will work after deployment to a real Node.js environment (Netlify, Vercel, EC2, etc.) where Instant Client can be installed. But you cannot test it during Bolt development. The practical path forward has two branches: 1. Use ORDS for development AND production (simpler, works everywhere, slightly higher latency per query due to HTTP overhead) 2. Use ORDS for development, switch to oracledb for production (best performance, more complex setup) For most Bolt projects, option 1 (ORDS everywhere) is the right choice unless you need stored procedures, complex Oracle-specific SQL, or have performance-critical query volumes. The ORDS approach also means zero config changes when moving between environments.

1// ORACLE INTEGRATION OPTIONS:
2//
3// OPTION 1: ORDS (Oracle REST Data Services) — works EVERYWHERE including Bolt WebContainer
4// - HTTP/HTTPS based, uses fetch()
5// - Works in: Bolt preview, Netlify, Vercel, local Node.js
6// - Setup: DBA enables ORDS on your Oracle schema
7// - Oracle Cloud Autonomous DB: ORDS pre-enabled
8//
9// OPTION 2: Native oracledb driver — works ONLY after deployment
10// - Requires Oracle Instant Client (C library at OS level)
11// - Requires TCP connection to Oracle port 1521
12// - Works in: Netlify (with Instant Client layer), Vercel (with custom build), EC2/VPS
13// - Does NOT work in: Bolt WebContainer preview
14//
15// RECOMMENDATION:
16// - New projects: Consider Supabase (PostgreSQL) — HTTP-based, works natively in Bolt
17// - Existing Oracle: Use ORDS for Bolt development
18// - Enterprise production: oracledb after deployment if ORDS performance is a concern
19
20// Alternative (strongly recommended for new projects):
21// Supabase: https://supabase.com — PostgreSQL, HTTP-based, works in Bolt WebContainer

Oracle REST Data Services provides automatic REST endpoints for Oracle Database tables when enabled on a schema. The endpoint pattern for a table named EMPLOYEES would be: GET https://your-oracle-host/ords/myschema/employees/ (list all rows), GET /ords/myschema/employees/{id} (get by primary key), POST /ords/myschema/employees/ (insert), PUT /ords/myschema/employees/{id} (update), DELETE /ords/myschema/employees/{id} (delete). For Oracle Cloud Autonomous Database, the ORDS base URL is provided in the Oracle Cloud Console: navigate to your Autonomous Database instance → Database Actions → SQL Workshop → REST. The URL format is: https://{instance-id}.adb.{region}.oraclecloudapps.com/ords/{schema}/. For on-premises ORDS installation: the URL depends on how your DBA configured ORDS — it may be on port 8080 (standalone), 443 (with a reverse proxy), or integrated with Oracle WebLogic. Get the base URL from your Oracle DBA. Authentication for ORDS can be configured in several ways: Basic Auth (username/password), OAuth2 tokens (ORDS has a built-in OAuth server), or no auth (for development schemas only). For Bolt integration, Basic Auth with an ORDS-specific user is the simplest path. Create an ORDS REST-enabled user in Oracle DB: CREATE USER ords_api IDENTIFIED BY password; GRANT CONNECT, RESOURCE TO ords_api; Then configure this user in ORDS. Use these credentials in your .env file — never expose them to the browser. For custom queries beyond simple table CRUD, ORDS supports SQL Workshop (execute arbitrary SQL via POST), custom RESTful modules (define custom endpoints backed by SQL queries or PL/SQL procedures), and parameterized queries via REST-enabled modules. For a Bolt integration, the auto-enabled table endpoints plus SQL Workshop cover 95% of use cases.

1// lib/oracle.ts
2const BASE = process.env.ORACLE_ORDS_BASE_URL!;
3const USER = process.env.ORACLE_ORDS_USER!;
4const PASS = process.env.ORACLE_ORDS_PASSWORD!;
5
6const AUTH = Buffer.from(`${USER}:${PASS}`).toString('base64');
7
8async function oracleRequest<T>(
9  path: string,
10  options: RequestInit = {}
11): Promise<T> {
12  const res = await fetch(`${BASE}${path}`, {
13    ...options,
14    headers: {
15      Authorization: `Basic ${AUTH}`,
16      'Content-Type': 'application/json',
17      Accept: 'application/json',
18      ...options.headers,
19    },
20  });
21
22  if (!res.ok) {
23    let detail = `HTTP ${res.status}`;
24    try {
25      const err = await res.json() as { title?: string; detail?: string };
26      detail = err.detail ?? err.title ?? detail;
27    } catch { /* ignore parse error */ }
28    throw new Error(`Oracle ORDS error: ${detail}`);
29  }
30
31  return res.json();
32}
33
34export const oracle = {
35  getRows: <T>(table: string, params: Record<string, string | number> = {}) => {
36    const qs = new URLSearchParams(params as Record<string, string>).toString();
37    return oracleRequest<{ items: T[]; count: number; hasMore: boolean }>(
38      `/${table}/${qs ? '?' + qs : ''}`
39    );
40  },
41  getRow: <T>(table: string, id: string | number) =>
42    oracleRequest<T>(`/${table}/${id}`),
43  createRow: <T>(table: string, data: unknown) =>
44    oracleRequest<T>(`/${table}/`, {
45      method: 'POST',
46      body: JSON.stringify(data),
47    }),
48  updateRow: <T>(table: string, id: string | number, data: unknown) =>
49    oracleRequest<T>(`/${table}/${id}`, {
50      method: 'PUT',
51      body: JSON.stringify(data),
52    }),
53  deleteRow: (table: string, id: string | number) =>
54    oracleRequest<void>(`/${table}/${id}`, { method: 'DELETE' }),
55};

Create the Next.js API routes that expose Oracle data to the React frontend. The pattern is the same as any other API integration in Bolt: your frontend calls your own /api/ routes, and those routes call Oracle ORDS using the oracle helper from lib/oracle.ts. This proxy pattern keeps ORDS credentials server-side and lets you add business logic (validation, filtering, access control) before data reaches the client. For read-heavy dashboards or reports, the ORDS query approach works well: build parameterized API routes that construct the appropriate table fetch or SQL query based on validated frontend parameters. For complex Oracle-specific queries (JOINs across multiple tables, analytical functions, window queries), use ORDS SQL Workshop if your DBA has enabled it — POST arbitrary SQL to the ORDS SQL endpoint and get back result sets. SQL Workshop endpoint: POST to /ords/{schema}/_/sql with a JSON body containing the SQL statement. Response contains column metadata and row data. This is extremely powerful for building data-intensive dashboards since you can run any read-only Oracle query from the Bolt preview without any native driver. For write operations (INSERT, UPDATE, DELETE), ORDS table endpoints handle standard cases. For batch inserts or transactions involving multiple tables, use PL/SQL procedures exposed via ORDS custom RESTful modules — your DBA creates the REST endpoint, and your Bolt app calls it as a simple HTTP POST. TypeScript typing for Oracle data: ORDS returns rows in the items array. Define TypeScript interfaces matching your Oracle table columns. ORDS uses uppercase column names by default (Oracle stores column names in uppercase). You can configure ORDS to return lowercase or camelCase via ORDS configuration, or map them in your API route response.

1// app/api/employees/route.ts
2import { NextResponse } from 'next/server';
3import { oracle } from '@/lib/oracle';
4
5interface OracleEmployee {
6  EMPLOYEE_ID: number;
7  FIRST_NAME: string;
8  LAST_NAME: string;
9  EMAIL: string;
10  DEPARTMENT_ID: number;
11  JOB_ID: string;
12  HIRE_DATE: string;
13  SALARY: number;
14}
15
16function mapEmployee(e: OracleEmployee) {
17  return {
18    id: e.EMPLOYEE_ID,
19    firstName: e.FIRST_NAME,
20    lastName: e.LAST_NAME,
21    email: e.EMAIL,
22    departmentId: e.DEPARTMENT_ID,
23    jobId: e.JOB_ID,
24    hireDate: e.HIRE_DATE,
25    salary: e.SALARY,
26  };
27}
28
29export async function GET(request: Request) {
30  try {
31    const { searchParams } = new URL(request.url);
32    const params: Record<string, string> = {};
33    const department = searchParams.get('department');
34    if (department) params.q = JSON.stringify({ DEPARTMENT_ID: Number(department) });
35    const result = await oracle.getRows<OracleEmployee>('employees', params);
36    return NextResponse.json(result.items.map(mapEmployee));
37  } catch (error: unknown) {
38    const e = error as { message: string };
39    return NextResponse.json({ error: e.message }, { status: 500 });
40  }
41}
42
43export async function POST(request: Request) {
44  try {
45    const body = await request.json();
46    const { firstName, lastName, email, departmentId, jobId, salary } = body;
47    if (!firstName || !lastName || !email) {
48      return NextResponse.json(
49        { error: 'firstName, lastName, and email are required' },
50        { status: 400 }
51      );
52    }
53    const created = await oracle.createRow<OracleEmployee>('employees', {
54      FIRST_NAME: firstName,
55      LAST_NAME: lastName,
56      EMAIL: email,
57      DEPARTMENT_ID: departmentId,
58      JOB_ID: jobId,
59      SALARY: salary,
60    });
61    return NextResponse.json(mapEmployee(created), { status: 201 });
62  } catch (error: unknown) {
63    const e = error as { message: string };
64    return NextResponse.json({ error: e.message }, { status: 500 });
65  }
66}

Once you deploy to Netlify or a server environment, the native oracledb driver becomes available since Oracle Instant Client can be installed at the OS level. For Netlify specifically, you need to add an Instant Client layer to your build process. For a VPS (AWS EC2, DigitalOcean, etc.), install Instant Client via the OS package manager before deploying. For Netlify deployments, the recommended approach is to use the oracle instant client via a Docker-based build or a custom Netlify build plugin that downloads and installs the Instant Client during the build phase. Alternatively, configure Netlify to use a Docker build image that includes Oracle Instant Client pre-installed. Consult Netlify's documentation on custom build environments for the current approach. For a VPS deployment: apt-get install libaio1 on Ubuntu/Debian, then download Oracle Instant Client Basic and BasicLite packages from oracle.com/database/technologies/instant-client, extract to /opt/oracle/instantclient, and set LD_LIBRARY_PATH. After this, oracledb loads and connects normally. The oracledb connection string format: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=your-oracle-host)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl))). For Oracle Cloud Autonomous Database, download the Wallet files from the Oracle Cloud console and configure the oracledb connection to use the wallet for mTLS authentication. For connection pooling (essential for serverless environments): oracledb.createPool() creates a pool of connections that are reused across function invocations. The same caching pattern used for mongoose in Next.js applies here — store the pool in a global variable to prevent creating a new pool on each request.

1// lib/oracle-native.ts (used post-deployment only)
2import oracledb from 'oracledb';
3
4let pool: oracledb.Pool | null = null;
5
6export async function getOraclePool(): Promise<oracledb.Pool> {
7  if (pool) return pool;
8  pool = await oracledb.createPool({
9    user: process.env.ORACLE_USER!,
10    password: process.env.ORACLE_PASSWORD!,
11    connectString: process.env.ORACLE_CONNECTION_STRING!,
12    poolMin: 2,
13    poolMax: 10,
14    poolIncrement: 1,
15  });
16  console.log('Oracle connection pool created');
17  return pool;
18}
19
20export async function query<T = Record<string, unknown>>(
21  sql: string,
22  binds: unknown[] | Record<string, unknown> = []
23): Promise<T[]> {
24  const p = await getOraclePool();
25  const conn = await p.getConnection();
26  try {
27    const result = await conn.execute<T>(
28      sql,
29      binds,
30      { outFormat: oracledb.OUT_FORMAT_OBJECT }
31    );
32    return result.rows ?? [];
33  } finally {
34    await conn.close();
35  }
36}

Deploy your Bolt project to Netlify to test the full integration. For ORDS-based integration, deployment is straightforward — your Next.js API routes make HTTPS calls to the ORDS endpoint, and Netlify's serverless functions have full outbound networking. No special Oracle libraries are required on the Netlify deployment. Deploy via Bolt Settings → Applications → Netlify → Publish. In Netlify Dashboard → Site Settings → Environment Variables, add ORACLE_ORDS_BASE_URL, ORACLE_ORDS_USER, and ORACLE_ORDS_PASSWORD. If using the native driver post-deployment, add ORACLE_CONNECTION_STRING, ORACLE_USER, and ORACLE_PASSWORD. Trigger a redeploy after adding variables. For ORDS connectivity: your Oracle server (or Oracle Cloud instance) must be accessible from Netlify's serverless function IPs. Netlify uses AWS Lambda, which has dynamic IPs — you cannot use static IP allowlisting. If your Oracle server has a firewall that restricts incoming connections, you must either open it to all IPs with authentication, or use Oracle Cloud's network access controls (security lists) that allow all IPs but require valid credentials. For Oracle Cloud Autonomous Database, Network Access is configurable per-instance. Monitor ORDS connectivity using the /api/health endpoint: test a simple ORDS call and return the status. If the ORDS call fails after deployment, check Netlify function logs for network errors. Common issues: ORDS server IP/hostname not accessible from Netlify, incorrect credentials, or ORDS schema not REST-enabled. Webhook-like real-time Oracle events (Oracle Advanced Queuing, Oracle Change Notification) require incoming TCP connections to your app, which means they only work with a deployed URL. Bolt WebContainer's lack of a public URL makes testing these impossible during development — simulate with polling or deploy first.

1# netlify.toml
2[build]
3  command = "npm run build"
4  publish = ".next"
5
6[build.environment]
7  NODE_VERSION = "20"
8
9[[plugins]]
10  package = "@netlify/plugin-nextjs"