> For the complete documentation index, see [llms.txt](https://crystal-garage.gitbook.io/lustra-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://crystal-garage.gitbook.io/lustra-docs/additional-and-advanced-features/handling-multi-connection.md).

# Handling multiple connections

Lustra uses the `default` connection unless a model or query selects another connection.

## Register Connections

Register the default connection with one URL.

```crystal
Lustra::SQL.init(ENV["DATABASE_URL"])
```

Register a named connection with `init(name, url)` or `add_connection`.

```crystal
Lustra::SQL.init("secondary", ENV["SECONDARY_DATABASE_URL"])

Lustra::SQL.add_connection("archive", ENV["ARCHIVE_DATABASE_URL"])
```

You can also initialize several connections from a hash.

```crystal
connections = {} of Lustra::SQL::Symbolic => String
connections["default"] = ENV["DATABASE_URL"]
connections["legacy"] = ENV["LEGACY_DATABASE_URL"]

Lustra::SQL.init(connections)
```

## Model Connection

Set `self.connection` on a model to make all model queries use a named connection.

```crystal
class PostStat
  include Lustra::Model

  self.connection = "secondary"
  self.table = "post_stats"

  column id : Int32, primary: true, presence: false
  column post_id : Int32
end
```

Models without an explicit connection use `default`.

```crystal
Post.connection
# => "default"

PostStat.connection
# => "secondary"
```

## Low-Level Queries

Use `use_connection` on low-level SQL builders.

```crystal
Lustra::SQL.select
  .from(:post_stats)
  .use_connection("secondary")
  .fetch do |row|
    puts row["post_id"]
  end
```

Transactions accept a connection name.

```crystal
Lustra::SQL.transaction("secondary") do
  PostStat.query.create!(post_id: 1)
end
```

Keep all queries inside a named transaction on the same connection. A query that selects a different connection name uses another pool and is not part of that transaction.

## Migrations

The migration manager runs on the default connection. If you need schema changes on another database, run a separate migration setup against that database.

Avoid associations between models stored in different databases. Lustra cannot make cross-database joins work unless PostgreSQL itself can see both relations through the same connection.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://crystal-garage.gitbook.io/lustra-docs/additional-and-advanced-features/handling-multi-connection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.