====== Runbook: DSN-Export ======

<WRAP round info>
**Durata:** ~5 minuti \\
**Ruolo:** Sysadmin, DBA \\
**Applicazione:** Migrazione, Documentazione, Disaster Recovery
</WRAP>

Export e import di definizioni DSN (Data Source Names).

----

===== Workflow =====

<mermaid>
flowchart TD
    A[Start] --> B{Obiettivo?}
    B -->|Export| C[Estrarre DSN da Config]
    B -->|Import| D[Inserire DSN in Config]
    C --> E[Salvare JSON]
    D --> F[Riavviare Gateway]
    E --> G[Finito]
    F --> H[Testare DSN]
    H --> G

    style G fill:#e8f5e9
</mermaid>

----

===== 1. Struttura DSN =====

I DSN sono definiti in ''appsettings.json'':

<code json>
{
  "Gateway": {
    "Databases": {
      "demo": {
        "Provider": "sqlite",
        "ConnectionString": "Data Source=data/demo.db"
      },
      "produzione": {
        "Provider": "sqlserver",
        "ConnectionString": "Server=sql01;Database=ProdDB;User Id=app;Password=***"
      },
      "reporting": {
        "Provider": "postgresql",
        "ConnectionString": "Host=pg01;Database=reports;Username=reader;Password=***"
      }
    }
  }
}
</code>

----

===== 2. Esportare DSN =====

**Con jq (Linux/macOS):**

<code bash>
# Esportare tutti i DSN come JSON
jq '.Gateway.Databases' appsettings.json > dsn-export.json

# Esportare singolo DSN
jq '.Gateway.Databases.produzione' appsettings.json > produzione-dsn.json

# Elencare nomi DSN
jq -r '.Gateway.Databases | keys[]' appsettings.json
</code>

**Con PowerShell (Windows):**

<code powershell>
# Caricare JSON
$config = Get-Content "appsettings.json" | ConvertFrom-Json

# Esportare tutti i DSN
$config.Gateway.Databases | ConvertTo-Json -Depth 10 | Out-File "dsn-export.json"

# Elencare nomi DSN
$config.Gateway.Databases.PSObject.Properties.Name
</code>

----

===== 3. Importare DSN =====

**Con jq (Linux):**

<code bash>
# Inserire DSN da file export in Config
jq --slurpfile dsn dsn-export.json '.Gateway.Databases = $dsn[0]' appsettings.json > appsettings.new.json

# Backup e sostituire
cp appsettings.json appsettings.json.bak
mv appsettings.new.json appsettings.json
</code>

**Con PowerShell (Windows):**

<code powershell>
# Caricare Config esistente
$config = Get-Content "appsettings.json" | ConvertFrom-Json

# Caricare Export
$dsnExport = Get-Content "dsn-export.json" | ConvertFrom-Json

# Sostituire DSN
$config.Gateway.Databases = $dsnExport

# Salvare
$config | ConvertTo-Json -Depth 10 | Out-File "appsettings.json" -Encoding UTF8
</code>

----

===== 4. Aggiungere Singolo DSN =====

**Con jq:**

<code bash>
# Aggiungere nuovo DSN
jq '.Gateway.Databases.nuovodb = {
    "Provider": "mysql",
    "ConnectionString": "Server=mysql01;Database=newdb;User=app;Password=secret"
}' appsettings.json > appsettings.new.json

mv appsettings.new.json appsettings.json
</code>

**Con PowerShell:**

<code powershell>
$config = Get-Content "appsettings.json" | ConvertFrom-Json

# Nuovo DSN come PSObject
$newDsn = [PSCustomObject]@{
    Provider = "mysql"
    ConnectionString = "Server=mysql01;Database=newdb;User=app;Password=secret"
}

# Aggiungere
$config.Gateway.Databases | Add-Member -Name "nuovodb" -Value $newDsn -MemberType NoteProperty

$config | ConvertTo-Json -Depth 10 | Out-File "appsettings.json" -Encoding UTF8
</code>

----

===== 5. Migrare DSN tra Ambienti =====

**Export da Produzione:**

<code bash>
# Su server Prod
ssh prod-gateway "jq '.Gateway.Databases' /opt/data-gateway/appsettings.json" > prod-dsn.json
</code>

**Import in Staging (con adattamento password):**

<code bash>
# Sostituire password con quelle staging
jq '.produzione.ConnectionString = "Server=sql-staging;Database=ProdDB;User Id=app;Password=staging-pwd"' \
    prod-dsn.json > staging-dsn.json

# Importare in Staging
scp staging-dsn.json staging-gateway:/tmp/
ssh staging-gateway "jq --slurpfile dsn /tmp/staging-dsn.json \
    '.Gateway.Databases = \$dsn[0]' /opt/data-gateway/appsettings.json > /tmp/new.json && \
    mv /tmp/new.json /opt/data-gateway/appsettings.json && \
    systemctl restart data-gateway"
</code>

----

===== 6. Riavviare Gateway =====

Dopo modifiche DSN:

<code bash>
# Linux
sudo systemctl restart data-gateway

# Windows
Restart-Service -Name "DataGateway"

# Docker
docker restart gateway
</code>

----

===== 7. Testare DSN =====

<code bash>
# Testare tutti i DSN
for dsn in $(jq -r '.Gateway.Databases | keys[]' appsettings.json); do
    echo -n "Testing $dsn: "
    curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:5000/api/v1/dsn/$dsn/tables"
done
</code>

**Output atteso:**

<code>
Testing demo: 200
Testing produzione: 200
Testing reporting: 200
</code>

----

===== 8. Checklist =====

| # | Punto di verifica | v |
|---|-----------|---|
| 1 | DSN esportato | ☐ |
| 2 | File export salvato | ☐ |
| 3 | Password non in chiaro nell'export | ☐ |
| 4 | Import eseguito | ☐ |
| 5 | Gateway riavviato | ☐ |
| 6 | Tutti i DSN testati | ☐ |

----

===== Troubleshooting =====

| Problema | Causa | Soluzione |
|---------|---------|--------|
| ''jq: parse error'' | JSON non valido | Validare JSON |
| DSN non trovato | Gateway non riavviato | Restart |
| ''Connection failed'' | Connection String errato | Verificare credenziali |
| Problemi encoding | Encoding errato | Usare UTF-8 |

----

===== Note sulla Sicurezza =====

<WRAP round important>
**Password negli Export:**
  * Mai committare password in Git
  * Crittografare o eliminare file export
  * Usare variabili ambiente per credenziali:
<code json>
"ConnectionString": "Server=sql01;Database=ProdDB;User Id=${DB_USER};Password=${DB_PASS}"
</code>
</WRAP>

----

===== Runbook Correlati =====

  * [[.:config-backup|Config-Backup]] - Backup completo
  * [[..:tagesgeschaeft:dsn-verwalten|Gestire DSN]] - Amministrazione DSN
  * [[..:tagesgeschaeft:server-starten|Avviare server]] - Dopo Import

----

<< [[.:config-backup|<- Config-Backup]] | [[..:start|-> Panoramica Operatore]] >>

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Data Gateway Professional//

{{tag>operator runbook dsn export import migration}}