Attach databases

SQLite's ATTACH DATABASE makes another database file available through an existing connection. You give it a schema name, then use that name to distinguish tables in the attached file from tables in the main database. This is useful when one query needs data from both files.

In NitroSQLite, call attach() on an open connection. The alias becomes the SQLite schema name. Use the same platform root and relative location convention as open().

import { open } from 'react-native-nitro-sqlite'

const db = open({ name: 'app.sqlite' })

db.attach('archive.sqlite', 'archive', 'databases')

const { results } = db.execute(
  `SELECT main.notes.id, archive.history.note
   FROM main.notes
   JOIN archive.history ON archive.history.note_id = main.notes.id`,
)

db.detach('archive')
db.close()

The example assumes the tables and files already exist. SQLite can create the attached file when it is missing, so verify the intended path when opening prepopulated data. attach() and detach() are synchronous connection operations; they fail while the connection queue is busy. A failed attach or detach throws NitroSQLiteError through the connection wrapper.

The native implementation inserts the attached file path and alias into SQL. Use application-controlled database names, locations, and aliases rather than arbitrary user input. Query values still belong in ? parameters. See database lifecycle for the location convention and the connection API for signatures.