spanner-orm

library0.2.2jsnpmunverified

A TypeScript ORM for Google Cloud Spanner and PostgreSQL (including PGLite), inspired by Drizzle ORM. Current stable version is 0.2.2. It allows you to define a single schema using a composable, Drizzle-inspired syntax and then migrate or query both databases with dialect-aware SQL generation. Key differentiators include cross-dialect migrations, a fluent query builder, raw SQL fallback via template literals, and support for dynamic default values. It ships with TypeScript types and requires peer dependencies @google-cloud/spanner, pg, and @electric-sql/pglite depending on the target database. Development is at an early stage with frequent breaking changes likely.

database

npm install spanner-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPANNER-ORM

spanner-orm

databasejavascriptv0.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

spanner-orm

✓ import { defineSchema, defineTable, defineAttr, sql } from 'spanner-orm'

✗ const spannerOrm = require('spanner-orm')

The library is ESM-only; CommonJS requires dynamic import or bundler. Named exports are the primary interface.

defineSchema

✓ import { defineSchema } from 'spanner-orm'

✗ import { defineSchema } from 'spanner-orm/schema'

All public API symbols are exported from the main entry point. Do not use subpath imports.

QueryBuilder

✓ import { QueryBuilder } from 'spanner-orm'

✗ import { QueryBuilder } from 'spanner-orm/query'

QueryBuilder is exported from the main package, not a submodule.

sql

✓ import { sql } from 'spanner-orm'

✗ import { sql } from 'spanner-orm/sql'

sql is a template tag function, exported from the top-level package.

Defines a simple user schema with UUID primary key, timestamps, and queries for users using the query builder.

import { defineSchema, defineTable, defineAttr, sql } from 'spanner-orm'; const schema = defineSchema({ users: defineTable({ id: defineAttr('uuid', { default: sql`gen_random_uuid()` }), name: defineAttr('string'), email: defineAttr('string', { unique: true }), createdAt: defineAttr('timestamp', { default: sql`now()` }), }), }); // For PostgreSQL import { Client } from 'pg'; const client = new Client({ connectionString: process.env.DATABASE_URL ?? '' }); await client.connect(); // Use the ORM's query builder const users = await schema.users.findMany(client, { where: { name: { eq: 'Alice' } } }); console.log(users); await client.end();

Debug

Known issues

breakingAPI is unstable and may change significantly between minor versions.

fix

Pin to exact version and test upgrades thoroughly.

affects: 0.x

deprecatedThe `defineSchema` function signature may change to accept an object directly instead of a callback in future versions.

fix

Use the current object-based syntax and monitor changelog for migration guides.

affects: <1.0

breakingPeer dependencies are not automatically installed; you must install them manually.

fix

Run `npm install @google-cloud/spanner pg @electric-sql/pglite` as needed.

affects: >=0.1

gotchaDefault values using `sql` template tags are evaluated at schema definition time, not at query time.

fix

Use `$defaultFn` for dynamic defaults like `crypto.randomUUID()`.

affects: >=0.1

gotchaSpanner does not support `ON DELETE CASCADE`; you must handle cascading deletes manually.

fix

Implement application-level cascading deletes for Spanner.

affects: >=0.1

Errors

Common errors & fixes

Cannot find module 'spanner-orm'

Package not installed or ESM import used without proper configuration.

fix

Install the package: `npm install spanner-orm@0.2.2`. Ensure your project uses ESM (type: module in package.json) or use a bundler.

TypeError: db.users.findMany is not a function

Using the ORM without a client instance.

fix

Ensure you pass a valid database client (pg.Client or Spanner instance) to the query methods.

Error: No dialect specified

You must specify dialect when creating the ORM instance.

fix

Use `new SpannerOrm({ dialect: 'postgres' })` or `{ dialect: 'spanner' }`.

Upgrade

Version history

0.2.2latest on npm

Audit

Dependencies

@google-cloud/spanneroptionalRequired for Google Cloud Spanner support

pgoptionalRequired for PostgreSQL support

@electric-sql/pgliteoptionalRequired for PGLite support

Agent activity

9 hits · last 30 days

node