Выражения ATTACH и DETACH

DuckDB позволяет подключаться к файлам баз данных и отключаться от них.

Примеры

Подключите базу данных file.db с псевдонимом, определяемым по имени (file):

ATTACH 'file.db';

Подключите базу данных file.db с явным псевдонимом (file_db):

ATTACH 'file.db' AS file_db;

Подключите базу данных file.db в режиме только для чтения:

ATTACH 'file.db' (READ_ONLY);

Подключите базу данных file.db с размером блока 16 КБ:

ATTACH 'file.db' (BLOCK_SIZE 16384);

Подключите базу данных SQLite для чтения и записи (см. sqlite расширение для получения дополнительной информации):

ATTACH 'sqlite_file.db' AS sqlite_db (TYPE SQLITE);

Подключите базу данных file.db, если псевдоним базы данных file еще не существует:

ATTACH IF NOT EXISTS 'file.db';

Подключите базу данных file.db, если явный псевдоним базы данных file_db еще не существует:

ATTACH IF NOT EXISTS 'file.db' AS file_db;

Создайте таблицу в подключенной базе данных с псевдонимом file:

CREATE TABLE file.new_table (i INTEGER);

Отключите базу данных с псевдонимом file:

DETACH file;

Показать список всех подключенных баз данных:

SHOW DATABASES;

Изменить базу данных по умолчанию на базу данных file:

USE file;

Подключить

Выражение ATTACH добавляет новый файл базы данных в каталог, который можно читать и к которому можно обращаться. Обратите внимание, что определения подключений не сохраняются между сеансами: при запуске нового сеанса вам нужно повторно подключиться ко всем базам данных.

Синтаксис ATTACH

ATTACH позволяет DuckDB работать с несколькими файлами баз данных и позволяет передавать данные между различными файлами баз данных.

ATTACH поддерживает HTTP- и S3-пункты конечных точек. Для них по умолчанию создается подключение только для чтения. Поэтому следующие две команды эквивалентны:

ATTACH 'https://blobs.duckdb.org/databases/stations.duckdb' AS stations_db;
ATTACH 'https://blobs.duckdb.org/databases/stations.duckdb' AS stations_db (READ_ONLY);

Аналогично, следующие две команды, подключающиеся к S3, эквивалентны:

ATTACH 's3://duckdb-blobs/databases/stations.duckdb' AS stations_db;
ATTACH 's3://duckdb-blobs/databases/stations.duckdb' AS stations_db (READ_ONLY);

До версии DuckDB 1.1.0 для HTTP- и S3-пунктов конечных точек необходимо было указывать флаг READ_ONLY.

Отключить

Выражение DETACH позволяет закрывать и отключать ранее подключенные файлы баз данных, освобождая любые блокировки, удерживаемые на файле базы данных.

Обратите внимание, что отключиться от базы данных по умолчанию невозможно: если вы хотите это сделать, используйте выражение USE для изменения базы данных по умолчанию на другую. Например, если вы подключены к постоянной базе данных, вы можете переключиться на базу данных в памяти, вызвав:

ATTACH ':memory:' AS memory_db;
USE memory_db;

Предупреждение Закрытие подключения, например, вызов функции close() в Python, не освобождает блокировки, удерживаемые на файлах баз данных, так как дескрипторы файлов удерживаются основным экземпляром DuckDB (в случае Python модуль duckdb).

Синтаксис DETACH

Параметры

Квалификация имён

Полное имя каталожных объектов содержит каталог, схему и имя объекта. Например:

Подключите базу данных new_db:

ATTACH 'new_db.db';

Создайте схему my_schema в базе данных new_db:

CREATE SCHEMA new_db.my_schema;

Создайте таблицу my_table в схеме my_schema:

CREATE TABLE new_db.my_schema.my_table (col INTEGER);

Обратитесь к столбцу col внутри таблицы my_table:

SELECT new_db.my_schema.my_table.col FROM new_db.my_schema.my_table;

Обратите внимание, что часто полное имя не требуется. Когда имя не квалифицировано полностью, система ищет, какие записи необходимо использовать, используя путь поиска каталога. Путь поиска каталога по умолчанию включает системный каталог, временный каталог и подключенную по умолчанию базу данных вместе со схемой main.

Также обратите внимание на правила по идентификаторам и именам баз данных, в частности.

База данных и схема по умолчанию

При создании таблицы без квалификации таблица создается в схеме по умолчанию в базе данных по умолчанию. База данных по умолчанию — это база данных, которая запускается при создании системы, а схема по умолчанию — main.

Создайте таблицу my_table в базе данных по умолчанию:

CREATE TABLE my_table (col INTEGER);

Изменение базы данных и схемы по умолчанию

Базу данных и схему по умолчанию можно изменить, используя команду USE.

Установите схему базы данных по умолчанию на new_db.main:

USE new_db;

Установите схему базы данных по умолчанию на new_db.my_schema:

USE new_db.my_schema;

Разрешение конфликтов

При предоставлении только одной квалификации система может интерпретировать это как либо каталог, либо схему, если нет конфликтов. Например:

ATTACH 'new_db.db';
CREATE SCHEMA my_schema;

Создаёт таблицу new_db.main.tbl:

CREATE TABLE new_db.tbl (i INTEGER);

Создаёт таблицу default_db.my_schema.tbl:

CREATE TABLE my_schema.tbl (i INTEGER);

Если мы создаём конфликт (т.е. у нас есть и схема, и каталог с одинаковым именем), система запросит использование полного пути вместо этого:

CREATE SCHEMA new_db;
CREATE TABLE new_db.tbl (i INTEGER);

Error: Binder Error: Ambiguous reference to catalog or schema "new_db" -
use a fully qualified path like "memory.new_db"

Изменение пути поиска каталога

Путь поиска каталога можно настроить, установив параметр конфигурации search_path, который использует список значений, разделённых запятыми, которые будут в пути поиска. Следующий пример демонстрирует поиск в двух базах данных:

ATTACH ':memory:' AS db1;
ATTACH ':memory:' AS db2;
CREATE table db1.tbl1 (i INTEGER);
CREATE table db2.tbl2 (j INTEGER);

Ссылка на таблицы с использованием их полного имени:

SELECT * FROM db1.tbl1;
SELECT * FROM db2.tbl2;

Или установите путь поиска и ссылайтесь на таблицы по их имени:

SET search_path = 'db1,db2';
SELECT * FROM tbl1;
SELECT * FROM tbl2;

Семантика транзакций

При выполнении запросов на нескольких базах данных система открывает отдельные транзакции для каждой базы данных. Транзакции начинаются по умолчанию лениво — когда к заданной базе данных впервые обращаются в запросе, для этой базы данных будет начата транзакция. SET immediate_transaction_mode = true может быть переключен, чтобы изменить это поведение на жадное начало транзакций во всех подключенных базах данных вместо этого.

Хотя несколько транзакций могут быть активны одновременно — система поддерживает запись только в одной подключенной базе данных в одной транзакции. Если вы попытаетесь записать в несколько подключенных баз данных в одной транзакции, будет выброшено следующее сообщение об ошибке:

Attempting to write to database "db2" in a transaction that has already modified database "db1" -
a single transaction can only write to a single attached database.

Причина этого ограничения заключается в том, что система не поддерживает атомарность для транзакций между подключенными базами данных. Транзакции атомарны только внутри каждого файла базы данных. Ограничив глобальную транзакцию записью только в один файл базы данных, гарантируется атомарность.