Name

ATTACH DATABASE — Attach a database file

Syntax

Common Usage

ATTACH DATABASE 'filename' AS database_name;

Description

The ATTACH DATABASE command associates the database file filename with the current database connection under the logical database name database_name . If the database file filename does not exist, it will be created. Once attached, all references to a specific database are done via the logical database name, not the filename. All database names must be unique, but (when shared cache mode is not enabled) attaching the same filename multiple times under different database names is properly supported.

The database name main is reserved for the primary database (the one that was used to create the database connection). The database name temp is reserved for the database that holds temporary tables and other temporary data objects. Both of these database names exist for every database connection.

If the filename :memory: is given, a new in-memory database will be created and attached. Multiple in-memory databases can be attached, but they will each be unique. If an empty filename is given ( '' ), a temporary file-backed database will be created. Like an in-memory database, each database is unique and all temporary databases are automatically deleted when they are closed. Unlike an in-memory database, file-based temporary databases can grow to large sizes without consuming excessive memory.

All databases attached to a database connection must share the same text encoding as the main database. If you attempt to attach a database that has a different text encoding, an SQLite logic error will be returned.

If the main database was opened with sqlite3_open_v2(), each attached database will be opened with the same flags. If the main database was opened read-only, all attached databases will also be read-only.

Associating more than one database to the same database connection enables the execution of SQL statements that reference tables from different database files. Transactions that involve multiple databases are atomic, assuming the main database is not an in-memory database. In that case, transactions within a given database file continue to be atomic, but operations that bridge database files may not be atomic.

If any write operations are performed on any database, a master journal file will be created in association with the main database. If the main database is located in a read-only area, the master journal file cannot be created and the operation will fail. If some databases are read-only and some are read/write, make sure the main database is one of the databases that is located in a read/write area.

Any place SQLite expects a table name, it will accept the format database_name.table_name. This can be used to refer to a table within a specific database that might otherwise be ambiguous.

See Also

DETACH DATABASE, encoding [PRAGMA, Ap F], temp_store [PRAGMA, Ap F], sqlite3_open() [C API, Ap G]