{"id":43504,"library":"offshore-sql","title":"Offshore SQL Adapter","description":"SQL database adapter for the Offshore ORM, providing support for MySQL, PostgreSQL, and SQLite. Current stable version is 1.0.9. Release cadence is irregular, with infrequent updates. Key differentiator: bridges Offshore's query language to SQL backends, but note that Offshore itself is a less common ORM compared to alternatives like Sequelize or Knex. Requires offshore core as peer dependency. ESM-only from v1.0.0.","status":"active","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/Atlantis-Software/offshore-sql","tags":["javascript","orm","offshore","sql"],"install":[{"cmd":"npm install offshore-sql","lang":"bash","label":"npm"},{"cmd":"yarn add offshore-sql","lang":"bash","label":"yarn"},{"cmd":"pnpm add offshore-sql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: the adapter requires offshore ORM core to function.","package":"offshore","optional":false}],"imports":[{"note":"ESM-only since v1.0.0. CommonJS require will fail.","wrong":"const adapter = require('offshore-sql')","symbol":"default (adapter)","correct":"import adapter from 'offshore-sql'"},{"note":"Type import only; Adapter is a TypeScript type, not a value.","wrong":"import { Adapter } from 'offshore-sql'","symbol":"type Adapter","correct":"import type { Adapter } from 'offshore-sql'"},{"note":"Named export, ESM-only.","wrong":"const { AdapterConfig } = require('offshore-sql')","symbol":"AdapterConfig","correct":"import { AdapterConfig } from 'offshore-sql'"}],"quickstart":{"code":"import offshore from 'offshore';\nimport sqlAdapter from 'offshore-sql';\nimport { AdapterConfig } from 'offshore-sql';\n\nconst config: AdapterConfig = {\n  client: 'pg',\n  connection: {\n    host: process.env.DB_HOST ?? 'localhost',\n    port: 5432,\n    user: process.env.DB_USER ?? 'user',\n    password: process.env.DB_PASSWORD ?? '',\n    database: process.env.DB_NAME ?? 'mydb'\n  }\n};\n\nconst orm = new offshore.Offshore();\norm.registerAdapter('sql', sqlAdapter(config));\n\nconst User = orm.defineModel('user', {\n  attributes: {\n    name: { type: 'string' },\n    email: { type: 'string', required: true }\n  }\n});\n\nasync function run() {\n  await orm.initialize();\n  const users = await User.find({});\n  console.log(users);\n  await orm.teardown();\n}\n\nrun().catch(console.error);","lang":"typescript","description":"Initializes Offshore ORM with the SQL adapter, defines a model, and queries all users."},"warnings":[{"fix":"Use import statements instead of require().","message":"offshore-sql v1.0.0 dropped CommonJS support. All imports must use ESM syntax.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use offshore's migrate or sync methods after initializing.","message":"The adapter does not automatically create tables; you must run migrations or sync manually.","severity":"gotcha","affected_versions":"<=1.0.9"},{"fix":"Upgrade MySQL to version 8 or later.","message":"Support for MySQL 5.x is deprecated; MySQL 8+ recommended.","severity":"deprecated","affected_versions":">=1.0.5"},{"fix":"Access the underlying knex instance via adapter.knex to run transactions.","message":"Transactions are not supported in this adapter; use raw queries via knex.","severity":"gotcha","affected_versions":"<=1.0.9"}],"env_vars":null,"search_vec":"'1.0.9':22 'adapt':3,6 'altern':52 'backend':39 'bridg':32 'cadenc':24 'common':48 'compar':50 'core':59 'current':18 'databas':5 'depend':62 'differenti':31 'esm':64 'esm-on':63 'infrequ':28 'irregular':26 'javascript':68 'key':30 'knex':56 'languag':36 'less':47 'like':53 'mysql':14 'note':41 'offshor':1,9,33,43,58,70 'orm':10,49,69 'peer':61 'postgresql':15 'provid':11 'queri':35 'releas':23 'requir':57 'sequel':54 'sql':2,4,38,71 'sqlite':17 'stabl':19 'support':12 'updat':29 'v1.0.0':67 'version':20","created_at":"2026-06-05T17:00:07.069496+00:00","updated_at":"2026-06-05T17:00:07.069496+00:00","problems":[{"fix":"Run 'npm install offshore-sql' and ensure your package.json has 'type': 'module' or use .mjs extension.","cause":"Package not installed or ESM module resolution issue.","error":"Error: Cannot find module 'offshore-sql'"},{"fix":"Replace require('offshore-sql') with import adapter from 'offshore-sql'.","cause":"Attempted to use CommonJS require() on ESM-only module.","error":"TypeError: adapter is not a function"},{"fix":"Verify DB_HOST, port, and that the database service is started.","cause":"Database server not running or connection config incorrect.","error":"Error: connect ECONNREFUSED ::1:5432"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Atlantis-Software/offshore-sql#readme","github":"https://github.com/Atlantis-Software/offshore-sql","docs":null,"changelog":null,"pypi":null,"npm":"offshore-sql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}