# Instalação Suricato em Oracle

## Visão Geral

A implantação em Oracle é voltada para ambientes que exigem alta disponibilidade e performance robusta. Embora o fluxo seja similar ao SQL Server, o Oracle possui exigências específicas de variáveis de ambiente e permissões que, se ignoradas, podem impedir a inicialização do sistema.

#### Preparação para a Versão 3.1

Para garantir o sucesso da nova interface, valide estes dois pontos antes de começar:

* **Caminho de Origem:** É obrigatório estar na versão 3.0.0.25.
* **Ambiente Web:** O PHP deve ser o 8.5.0 e o Servidor Web (Apache 2.4.66.0 ou IIS 10).

## Regras de Negócio

Transformamos as regras de negócio em um checklist de validação rápida:

* [x] **Privilégios:** Use sempre o usuário `SYS` com privilégio `SYSDBA`.
* [x] **Encoding:** O `NLS_LANG` deve ser `.AL32UTF8` para evitar erros de acentuação.
* [x] **Caminho Curto:** Copie os scripts para `C:\ACESSO`. Caminhos longos do Windows causam falhas no SQL\*Plus.
* [x] **Conexão:** O nome da conexão no ambiente de produção deve ser, obrigatoriamente, `SURICATO`.
* [x] **Ordenação:** A ordem dos scripts dentro de cada pasta deve respeitar o arquivo **Readme.txt.**

## Execução dos Scripts - Banco de Dados Oracle

> Os scripts "ensinam" ao Oracle como o Suricato armazena dados de acesso e ponto. Siga a ordem rigorosa para evitar erros de "tabela pai não encontrada".

#### Sequência de Pastas

Após finalizar a instalação, é necessário executar os scripts para criação e atualização do banco de dados.  Os arquivos estão localizados em:

```
C:\Program Files\Telematica\Suricato\oracle
```

As pastas devem ser executadas na seguinte ordem:

<table data-header-hidden><thead><tr><th width="78"></th><th width="172"></th><th></th></tr></thead><tbody><tr><td><strong>Ordem</strong></td><td><strong>Pasta</strong></td><td><strong>Objetivo</strong></td></tr><tr><td>1</td><td>Criação</td><td>Cria a estrutura base (pule se o banco já existir).</td></tr><tr><td>2</td><td>Atualização</td><td>Atualiza até a versão 2.10.11.69.</td></tr><tr><td>3</td><td>Migração v3.0</td><td>Prepara o banco para a interface 3.0.</td></tr><tr><td>4</td><td>Migração v3.1</td><td>Exclusivo v3.1: Novas tabelas de performance.</td></tr></tbody></table>

### Passo a Passo no CMD

#### Criação do Banco (Pasta 1)

> Objetivo: Construir a estrutura do zero. *Nota: Se o banco já existe, você pode pular esta etapa.*

{% stepper %}
{% step %}
**Prepare os arquivos:** Copie as pastas de `C:\Program Files\Telematica\Suricato\oracle` para `C:\ACESSO`.
{% endstep %}

{% step %}
Abra o arquivo **Readme.txt** para confirmar a ordem correta de execução dos scripts.
{% endstep %}

{% step %}
**Abra o CMD:** (Windows + R > `cmd`) Clique em Ok.
{% endstep %}

{% step %}
**Configure o Charset:** Digite `SET NLS_LANG=.AL32UTF8`.
{% endstep %}

{% step %}
**Conecte ao Banco como SYSDBA:** `SQLPLUS SYS/SENHA@IP_SERVIDOR/NOME_SID AS SYSDBA`
{% endstep %}

{% step %}
**Opcional, recomendado:** Copie os scripts para um diretório com caminho mais curto, por exemplo:  `C:\ACESSO`&#x20;
{% endstep %}

{% step %}
**Execute o Script:** `@"C:\ACESSO\SURICATO_DDL_1.sql";`\
O tempo de execução pode variar conforme o ambiente.

{% hint style="info" %}
**Importante:** Caso o banco já exista, esta etapa pode ser ignorada.
{% endhint %}

<figure><img src="/files/NjvqEWegRQ7NfvO461qv" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Atualização e Migração (Pastas 2, 3 e 4)

> Nestas etapas, o banco de dados é "ensinado" a lidar com as novas funcionalidades das versões recentes. As pastas 2, 3 e 4 são obrigatórias para a versão 3.1.0.0.

### Passo a Passo Replicável:

{% stepper %}
{% step %}

#### **Pasta 2 (v2.10.11.69):** Atualiza legados.&#x20;

* **Acesse:** <kbd>C:\Program Files\Telematica\Suricato\oracle\2</kbd>&#x20;
* Consulte o manual presente na pasta para identificar o script correto.
* Copie os scripts para `C:\ACESSO` (opcional).
* Execute o script indicado utilizando o mesmo comando:

  ```
  @"C:\ACESSO\NOME_DO_SCRIPT.sql";
  ```

{% endstep %}

{% step %}

#### **Pasta 3 (v3.0.0.0):** Prepara a estrutura

Repita o mesmo procedimento realizado na pasta **2**, agora utilizando os scripts da pasta **3** para migração para a versão 3.0.0.0.
{% endstep %}

{% step %}

#### **Pasta 4 (v3.1.0): V**ersão 3.1.

Uma nova pasta foi criada, a pasta **4**, e para migração, repita o mesmo procedimento realizado na pasta **3** para migração de versão.
{% endstep %}
{% endstepper %}

### Inicialização dos Serviços

Após a execução dos scripts, o sistema estará pronto para uso.

{% stepper %}
{% step %}
Abra os serviços do Windows:

* Pressione **Windows + R**
* Digite `services.msc`

Localize o serviço **Telematica Suricato**
{% endstep %}

{% step %}
Verifique se está em execução, caso não esteja, clique com o botão direito e selecione **Iniciar.**
{% endstep %}

{% step %}
Verifique também os serviços do Oracle:

* `OracleServiceNOME_DO_SID`
* `OracleOraDbVERSÃO_home1TNSListener`
* Com os serviços ativos, o Suricato estará apto para uso.

Recomenda-se manter o sistema sempre atualizado conforme novas versões forem disponibilizadas.

<figure><img src="/files/wDwuYp9DiAVPigpozyOl" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Teste de Conexão - Ambiente Oracle

> Após rodar os scripts, você precisa dizer ao Suricato como encontrar essas tabelas.

### Acesso ao Ambiente de Produção

Para criar a conexão com o banco de dados:

{% stepper %}
{% step %}
Abra um navegador e acesse o endereço do servidor Suricato: `https://IPdaMaquina/suricato/app/_lib/prod/`

**Exemplo:**

```
https://172.16.14.246/suricato/app/_lib/prod/
```

*<mark style="color:$primary;">**Nota (Versão 3.1):**</mark>* A partir da versão 3.1, o acesso foi simplificado para:\
`https://IPdaMaquina/suricato/prod/`

{% hint style="info" %}
**Atenção:** Verifique se o serviço **Telematica Suricato** está com status **"Em Execução"**. Caso não esteja, inicie o serviço.
{% endhint %}

<figure><img src="/files/LGtreKozhuEy8oZMavvG" alt=""><figcaption><p> <em>Serviço "Telemática Suricato"</em></p></figcaption></figure>
{% endstep %}

{% step %}
Será exibida a tela de acesso ao ambiente de produção.&#x20;

Na tela de autenticação, escreva um email de recuperação, selecione o idioma (pt-br ou en-us) e insira a senha `Tsi123!!` para liberar as opções de configuração.

Clique em **Entrar**.

{% hint style="warning" %}
Sugerimos utilizar a senha padrão do sistema para facilitar manutenções futuras, mas na versão **3.1** o administrador tem liberdade para definir uma senha personalizada.
{% endhint %}

<figure><img src="/files/zaVhdQvTrXChuM1K7lr8" alt=""><figcaption><p><em>Conectar ao Ambiente de Produção</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Configuração da Conexão

{% stepper %}
{% step %}
Para configurar a conexão, acesse a opção **Editar conexão**. O nome da conexão deve ser obrigatoriamente **SURICATO**.

<div align="center"><figure><img src="/files/8RIHmInKiHcAhUtGEhpX" alt=""><figcaption><p><em>Menu Ambiente de Produção</em></p></figcaption></figure></div>
{% endstep %}

{% step %}
Selecione o banco de dados desejado clicando no ícone correspondente.

<figure><img src="/files/y6NBiwl7axfrB4iBqi5c" alt=""><figcaption><p><em>Edição de Conexão</em></p></figcaption></figure>
{% endstep %}

{% step %}
Após selecionar, serão exibidas as configurações do banco. E Clique em **Testar Conexão** para validar.

<figure><img src="/files/EhK44U0cyZz24utXwkHs" alt=""><figcaption><p><em>Banco de Dados</em></p></figcaption></figure>

<figure><img src="/files/w7NpkguAtm2MbsMFRxg0" alt=""><figcaption><p><em>Conexão realizada com sucesso</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Possíveis Erros no Teste de Conexão

{% stepper %}
{% step %}

#### Variável de Ambiente TNS\_ADMIN

Defina a variável **TNS\_ADMIN** apontando para o diretório onde está o arquivo `tnsnames.ora`.  Exemplo:

```
C:\app\Administrator\product\11.2.0\dbhome_1\NETWORK\ADMIN
```

<figure><img src="/files/JlkiIYsT83Pwk3m8l5Hh" alt=""><figcaption><p><em>Variável de Ambiente TNS_ADMIN</em></p></figcaption></figure>
{% endstep %}

{% step %}

#### Configuração do PATH (Oracle)

No **PATH do Windows**, configure os diretórios do Oracle na seguinte ordem:

```
C:\app\Administrator\client_1;
C:\app\Administrator\product\11.2.0\dbhome_1\bin;
```

O diretório do **client deve vir primeiro**.

{% hint style="info" %}
**Observação:** O caminho do client deve apontar até o arquivo **oci.dll**.
{% endhint %}

<figure><img src="/files/CGDmho5DEZepnl1fzPas" alt=""><figcaption><p><em>Variável PATH Oracle</em></p></figcaption></figure>
{% endstep %}

{% step %}

#### Variável ORACLE\_HOME

* **Não deve existir** no servidor do Suricato
* Pode causar conflito com a conexão do PHP

Caso o erro persista após os ajustes:

* Reinicie o servidor do Suricato para aplicar as alterações
  {% endstep %}
  {% endstepper %}

#### Configuração do ORACLEINSTANTCLIENT (Erro com oci.dll)

Quando, ao configurar o ambiente de produção no Suricato, o erro de conexão persistir mesmo com o **PATH** corretamente configurado (Oracle Client e Oracle Server), pode ser necessário ajustar o caminho do **ORACLEINSTANTCLIENT**.

Esse erro ocorre porque o PHP não está conseguindo localizar o arquivo **oci.dll**, ou porque a versão da DLL não é compatível com a versão do PHP.

Para corrigir:

{% stepper %}
{% step %}
Adicione ao **PATH do Windows** o diretório do **ORACLEINSTANTCLIENT**, localizado dentro da pasta do Apache do Suricato.
{% endstep %}

{% step %}
Utilize a seguinte ordem no PATH (obrigatório):

```
C:\Program Files\Telematica\SURICATO\apache\oracleinstantclient;
C:\app\Administrator\product\11.2.0\client_1;
C:\app\Administrator\product\11.2.0\dbhome_1\BIN;
```

{% hint style="info" %}
**Importante:** O diretório **oracleinstantclient** deve sempre ser o primeiro da lista.
{% endhint %}
{% endstep %}

{% step %}
Após realizar a alteração, reinicie o servidor do Suricato para que o Windows reconheça as mudanças.

<figure><img src="/files/QrIeq8c1qHfgyfc1zzdF" alt=""><figcaption><p><em>Variável de Ambiente ORACLEINSTANTCLIENT</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Verificação do PHP (info.php)

O arquivo `info.php` permite validar as configurações do PHP.

**Exemplo de acesso:**

```
https://IP_SERVIDOR/suricato/info.php
```

* Verifique o parâmetro **PHPIniDir**

Ele indica qual arquivo `php.ini` está sendo utilizado

<figure><img src="/files/p7MQz28VxzqQBRMkAiVL" alt=""><figcaption><p><em>httpd.conf</em></p></figcaption></figure>

<figure><img src="/files/zbNvZDBFFGym7YVUj4Xi" alt=""><figcaption><p><em>info.php</em></p></figcaption></figure>

### Configuração do php.ini

{% stepper %}
{% step %}
Acesse o arquivo:

```
C:\Program Files\Telematica\SURICATO\Apache\php\php.ini
```

{% endstep %}

{% step %}
Verifique:

* Caminho das extensões
* Uso correto de barras (`/` ou `\`)
  {% endstep %}

{% step %}
Após alterações:

* Reinicie o serviço **Telematica Suricato**

<figure><img src="/files/W0bw6Oohqu5jVe8C3f1O" alt=""><figcaption><p><em>php.ini</em></p></figcaption></figure>

<figure><img src="/files/eul97f58Qeq68RLoVcsV" alt=""><figcaption><p> <em>info.php</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Verificação de Extensões PHP

* [x] No arquivo `php.ini`, verifique se as extensões estão habilitadas
* [x] Linhas **sem ponto e vírgula (;)** indicam que a extensão está ativa

Após reiniciar o serviço:

* [x] Acesse novamente o `info.php` e confirme se a extensão foi carregada

<figure><img src="/files/e1ocvV0wTNUyzlmbDA98" alt=""><figcaption><p><em>php.ini</em></p></figcaption></figure>

## FAQ - Perguntas Frequentes

<details>

<summary>Posso pular a execução da pasta 1?</summary>

Sim, apenas se o banco de dados já estiver criado previamente.

</details>

<details>

<summary>O que acontece se eu executar os scripts fora de ordem?</summary>

Pode causar inconsistências no banco ou falha na instalação. Sempre siga a ordem definida no Readme.txt.

</details>

<details>

<summary>Preciso usar obrigatoriamente o usuário SYS?</summary>

Sim. A criação e atualização do banco exigem privilégios elevados (SYSDBA).

</details>

<details>

<summary>Para que serve o comando <code>SET NLS_LANG=.AL32UTF8</code>?</summary>

Ele garante a correta codificação de caracteres durante a execução dos scripts, evitando erros com acentuação.

</details>

<details>

<summary>Posso executar os scripts direto da pasta de instalação?</summary>

Sim, mas não é recomendado. Caminhos longos podem causar erros — prefira copiar para um diretório mais curto.

</details>

<details>

<summary>O que fazer se um script demorar muito para executar?</summary>

Aguarde a finalização. O tempo pode variar conforme o desempenho do servidor.

</details>

<details>

<summary>Como sei se o banco foi criado/atualizado corretamente?</summary>

Se todos os scripts forem executados sem erro e o processo finalizar normalmente, o banco estará pronto.

</details>

<details>

<summary>O sistema não inicia após a instalação. O que verificar?</summary>

Verifique se:

* O serviço **Telematica Suricato** está em execução
* Os serviços do Oracle estão ativos

</details>

<details>

<summary>Preciso executar novamente os scripts após atualizar o sistema?</summary>

Depende da versão. Sempre siga o procedimento específico da atualização.

</details>


---

# Agent Instructions: 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:

```
GET https://software-telematica-com.gitbook.io/suricato-docs/central-tecnica/instalacao-e-configuracao-do-suricato/instalacao-do-suricato/instalacao-suricato-em-oracle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.